| Index: tools/telemetry/third_party/gsutilz/gslib/addlhelp/acls.py
|
| diff --git a/tools/telemetry/third_party/gsutilz/gslib/addlhelp/acls.py b/tools/telemetry/third_party/gsutilz/gslib/addlhelp/acls.py
|
| deleted file mode 100644
|
| index b9ac443f75d67259f214dbb8976c4a5ff95fd808..0000000000000000000000000000000000000000
|
| --- a/tools/telemetry/third_party/gsutilz/gslib/addlhelp/acls.py
|
| +++ /dev/null
|
| @@ -1,221 +0,0 @@
|
| -# -*- coding: utf-8 -*-
|
| -# Copyright 2012 Google Inc. All Rights Reserved.
|
| -#
|
| -# Licensed under the Apache License, Version 2.0 (the "License");
|
| -# you may not use this file except in compliance with the License.
|
| -# You may obtain a copy of the License at
|
| -#
|
| -# http://www.apache.org/licenses/LICENSE-2.0
|
| -#
|
| -# Unless required by applicable law or agreed to in writing, software
|
| -# distributed under the License is distributed on an "AS IS" BASIS,
|
| -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
| -# See the License for the specific language governing permissions and
|
| -# limitations under the License.
|
| -"""Additional help about Access Control Lists."""
|
| -
|
| -from __future__ import absolute_import
|
| -
|
| -from gslib.help_provider import HelpProvider
|
| -
|
| -_DETAILED_HELP_TEXT = ("""
|
| -<B>OVERVIEW</B>
|
| - Access Control Lists (ACLs) allow you to control who can read and write
|
| - your data, and who can read and write the ACLs themselves.
|
| -
|
| - If not specified at the time an object is uploaded (e.g., via the gsutil cp
|
| - -a option), objects will be created with a default object ACL set on the
|
| - bucket (see "gsutil help defacl"). You can replace the ACL on an object
|
| - or bucket using the "gsutil acl set" command, or
|
| - modify the existing ACL using the "gsutil acl ch" command (see "gsutil help
|
| - acl").
|
| -
|
| -
|
| -<B>BUCKET VS OBJECT ACLS</B>
|
| - In Google Cloud Storage, the bucket ACL works as follows:
|
| -
|
| - - Users granted READ access are allowed to list the bucket contents.
|
| -
|
| - - Users granted WRITE access are allowed READ access and also are
|
| - allowed to write and delete objects in that bucket -- including
|
| - overwriting previously written objects.
|
| -
|
| - - Users granted OWNER access are allowed WRITE access and also
|
| - are allowed to read and write the bucket's ACL.
|
| -
|
| - The object ACL works as follows:
|
| -
|
| - - Users granted READ access are allowed to read the object's data and
|
| - metadata.
|
| -
|
| - - Users granted OWNER access are allowed READ access and also
|
| - are allowed to read and write the object's ACL.
|
| -
|
| - A couple of points are worth noting, that sometimes surprise users:
|
| -
|
| - 1. There is no WRITE access for objects; attempting to set an ACL with WRITE
|
| - permission for an object will result in an error.
|
| -
|
| - 2. The bucket ACL plays no role in determining who can read objects; only the
|
| - object ACL matters for that purpose. This is different from how things
|
| - work in Linux file systems, where both the file and directory permission
|
| - control file read access. It also means, for example, that someone with
|
| - OWNER over the bucket may not have read access to objects in
|
| - the bucket. This is by design, and supports useful cases. For example,
|
| - you might want to set up bucket ownership so that a small group of
|
| - administrators have OWNER on the bucket (with the ability to
|
| - delete data to control storage costs), but not grant those users read
|
| - access to the object data (which might be sensitive data that should
|
| - only be accessed by a different specific group of users).
|
| -
|
| -
|
| -<B>CANNED ACLS</B>
|
| - The simplest way to set an ACL on a bucket or object is using a "canned
|
| - ACL". The available canned ACLs are:
|
| -
|
| - project-private
|
| - Gives permission to the project team based on their roles. Anyone who is
|
| - part of the team has READ permission, and project owners and project editors
|
| - have OWNER permission. This is the default ACL for newly created
|
| - buckets. This is also the default ACL for newly created objects unless the
|
| - default object ACL for that bucket has been changed. For more details see
|
| - "gsutil help projects".
|
| -
|
| - private
|
| - Gives the requester (and only the requester) OWNER permission for a
|
| - bucket or object.
|
| -
|
| - public-read
|
| - Gives all users (whether logged in or anonymous) READ permission. When
|
| - you apply this to an object, anyone on the Internet can read the object
|
| - without authenticating.
|
| -
|
| - NOTE: By default, publicly readable objects are served with a Cache-Control
|
| - header allowing such objects to be cached for 3600 seconds. If you need to
|
| - ensure that updates become visible immediately, you should set a
|
| - Cache-Control header of "Cache-Control:private, max-age=0, no-transform" on
|
| - such objects. For help doing this, see 'gsutil help setmeta'.
|
| -
|
| - NOTE: Setting a bucket ACL to public-read will remove all OWNER and WRITE
|
| - permissions from everyone except the project owner group. Setting an object
|
| - ACL to public-read will remove all OWNER and WRITE permissions from
|
| - everyone except the object owner. For this reason, we recommend using
|
| - the "acl ch" command to make these changes; see "gsutil help acl ch" for
|
| - details.
|
| -
|
| - public-read-write
|
| - Gives all users READ and WRITE permission. This ACL applies only to buckets.
|
| - NOTE: Setting a bucket to public-read-write will allow anyone on the
|
| - Internet to upload anything to your bucket. You will be responsible for this
|
| - content.
|
| -
|
| - NOTE: Setting a bucket ACL to public-read-write will remove all OWNER
|
| - permissions from everyone except the project owner group. Setting an object
|
| - ACL to public-read-write will remove all OWNER permissions from
|
| - everyone except the object owner. For this reason, we recommend using
|
| - the "acl ch" command to make these changes; see "gsutil help acl ch" for
|
| - details.
|
| -
|
| - authenticated-read
|
| - Gives the requester OWNER permission and gives all authenticated
|
| - Google account holders READ permission.
|
| -
|
| - bucket-owner-read
|
| - Gives the requester OWNER permission and gives the bucket owner READ
|
| - permission. This is used only with objects.
|
| -
|
| - bucket-owner-full-control
|
| - Gives the requester OWNER permission and gives the bucket owner
|
| - OWNER permission. This is used only with objects.
|
| -
|
| -
|
| -<B>ACL JSON</B>
|
| - When you use a canned ACL, it is translated into an JSON representation
|
| - that can later be retrieved and edited to specify more fine-grained
|
| - detail about who can read and write buckets and objects. By running
|
| - the "gsutil acl get" command you can retrieve the ACL JSON, and edit it to
|
| - customize the permissions.
|
| -
|
| - As an example, if you create an object in a bucket that has no default
|
| - object ACL set and then retrieve the ACL on the object, it will look
|
| - something like this:
|
| -
|
| - [
|
| - {
|
| - "entity": "group-00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7",
|
| - "entityId": "00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7",
|
| - "role": "OWNER"
|
| - },
|
| - {
|
| - "entity": "group-00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51",
|
| - "entityId": "00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51",
|
| - "role": "OWNER"
|
| - },
|
| - {
|
| - "entity": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71",
|
| - "entityId": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71",
|
| - "role": "READER"
|
| - }
|
| - ]
|
| -
|
| - The ACL consists collection of elements, each of which specifies an Entity
|
| - and a Role. Entities are the way you specify an individual or group of
|
| - individuals, and Roles specify what access they're permitted.
|
| -
|
| - This particular ACL grants OWNER to two groups (which means members
|
| - of those groups are allowed to read the object and read and write the ACL),
|
| - and READ permission to a third group. The project groups are (in order)
|
| - the project owners group, editors group, and viewers group.
|
| -
|
| - The 64 digit hex identifiers (following any prefixes like "group-") used in
|
| - this ACL are called canonical IDs. They are used to identify predefined
|
| - groups associated with the project that owns the bucket: the Project Owners,
|
| - Project Editors, and All Project Team Members groups. For more information
|
| - the permissions and roles of these project groups, see "gsutil help projects".
|
| -
|
| - Here's an example of an ACL specified using the group-by-email and
|
| - group-by-domain entities:
|
| -
|
| -[
|
| - {
|
| - "entity": "group-travel-companion-owners@googlegroups.com"
|
| - "email": "travel-companion-owners@googlegroups.com",
|
| - "role": "OWNER",
|
| - }
|
| - {
|
| - "domain": "example.com",
|
| - "entity": "domain-example.com"
|
| - "role": "READER",
|
| - },
|
| -]
|
| -
|
| - This ACL grants members of an email group OWNER, and grants READ
|
| - access to any user in a domain (which must be a Google Apps for Business
|
| - domain). By applying email group grants to a collection of objects
|
| - you can edit access control for large numbers of objects at once via
|
| - http://groups.google.com. That way, for example, you can easily and quickly
|
| - change access to a group of company objects when employees join and leave
|
| - your company (i.e., without having to individually change ACLs across
|
| - potentially millions of objects).
|
| -
|
| -
|
| -<B>SHARING SCENARIOS</B>
|
| - For more detailed examples how to achieve various useful sharing use
|
| - cases see https://developers.google.com/storage/docs/collaboration
|
| -""")
|
| -
|
| -
|
| -class CommandOptions(HelpProvider):
|
| - """Additional help about Access Control Lists."""
|
| -
|
| - # Help specification. See help_provider.py for documentation.
|
| - help_spec = HelpProvider.HelpSpec(
|
| - help_name='acls',
|
| - help_name_aliases=[
|
| - 'ACL', 'access control', 'access control list', 'authorization',
|
| - 'canned', 'canned acl'],
|
| - help_type='additional_help',
|
| - help_one_line_summary='Working With Access Control Lists',
|
| - help_text=_DETAILED_HELP_TEXT,
|
| - subcommand_help_text={},
|
| - )
|
|
|