| OLD | NEW |
|---|
| (Empty) |
| 1 # Copyright 2012 Google Inc. All Rights Reserved. | |
| 2 # | |
| 3 # Licensed under the Apache License, Version 2.0 (the "License"); | |
| 4 # you may not use this file except in compliance with the License. | |
| 5 # You may obtain a copy of the License at | |
| 6 # | |
| 7 # http://www.apache.org/licenses/LICENSE-2.0 | |
| 8 # | |
| 9 # Unless required by applicable law or agreed to in writing, software | |
| 10 # distributed under the License is distributed on an "AS IS" BASIS, | |
| 11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| 12 # See the License for the specific language governing permissions and | |
| 13 # limitations under the License. | |
| 14 | |
| 15 from gslib.help_provider import HELP_NAME | |
| 16 from gslib.help_provider import HELP_NAME_ALIASES | |
| 17 from gslib.help_provider import HELP_ONE_LINE_SUMMARY | |
| 18 from gslib.help_provider import HelpProvider | |
| 19 from gslib.help_provider import HELP_TEXT | |
| 20 from gslib.help_provider import HelpType | |
| 21 from gslib.help_provider import HELP_TYPE | |
| 22 | |
| 23 _detailed_help_text = (""" | |
| 24 <B>OVERVIEW</B> | |
| 25 Access Control Lists (ACLs) allow you to control who can read and write | |
| 26 your data, and who can read and write the ACLs themselves. | |
| 27 | |
| 28 If not specified at the time an object is uploaded (e.g., via the gsutil cp | |
| 29 -a option), objects will be created with a default object ACL set on the | |
| 30 bucket (see "gsutil help setdefacl"). You can replace the ACL on an object | |
| 31 or bucket using the gsutil setacl command (see "gsutil help setacl"), or | |
| 32 modify the existing ACL using the gsutil chacl command (see "gsutil help | |
| 33 chacl"). | |
| 34 | |
| 35 | |
| 36 <B>BUCKET VS OBJECT ACLS</B> | |
| 37 In Google Cloud Storage, the bucket ACL works as follows: | |
| 38 | |
| 39 - Users granted READ access are allowed to list the bucket contents. | |
| 40 | |
| 41 - Users granted WRITE access are allowed READ access and also are | |
| 42 allowed to write and delete objects in that bucket -- including | |
| 43 overwriting previously written objects. | |
| 44 | |
| 45 - Users granted FULL_CONTROL access are allowed WRITE access and also | |
| 46 are allowed to read and write the bucket's ACL. | |
| 47 | |
| 48 The object ACL works as follows: | |
| 49 | |
| 50 - Users granted READ access are allowed to read the object's data and | |
| 51 metadata. | |
| 52 | |
| 53 - Users granted FULL_CONTROL access are allowed READ access and also | |
| 54 are allowed to read and write the object's ACL. | |
| 55 | |
| 56 A couple of points are worth noting, that sometimes surprise users: | |
| 57 | |
| 58 1. There is no WRITE access for objects; attempting to set an ACL with WRITE | |
| 59 permission for an object will result in an error. | |
| 60 | |
| 61 2. The bucket ACL plays no role in determining who can read objects; only the | |
| 62 object ACL matters for that purpose. This is different from how things | |
| 63 work in Linux file systems, where both the file and directory permission | |
| 64 control file read access. It also means, for example, that someone with | |
| 65 FULL_CONTROL over the bucket may not have read access to objects in | |
| 66 the bucket. This is by design, and supports useful cases. For example, | |
| 67 you might want to set up bucket ownership so that a small group of | |
| 68 administrators have FULL_CONTROL on the bucket (with the ability to | |
| 69 delete data to control storage costs), but not grant those users read | |
| 70 access to the object data (which might be sensitive data that should | |
| 71 only be accessed by a different specific group of users). | |
| 72 | |
| 73 | |
| 74 <B>CANNED ACLS</B> | |
| 75 The simplest way to set an ACL on a bucket or object is using a "canned | |
| 76 ACL". The available canned ACLs are: | |
| 77 | |
| 78 project-private Gives permission to the project team based on their | |
| 79 roles. Anyone who is part of the team has READ | |
| 80 permission, and project owners and project editors | |
| 81 have FULL_CONTROL permission. This is the default | |
| 82 ACL for newly created buckets. This is also the | |
| 83 default ACL for newly created objects unless the | |
| 84 default object ACL for that bucket has been | |
| 85 changed. For more details see | |
| 86 "gsutil help projects". | |
| 87 | |
| 88 private Gives the requester (and only the requester) | |
| 89 FULL_CONTROL permission for a bucket or object. | |
| 90 | |
| 91 public-read Gives the requester FULL_CONTROL permission and | |
| 92 gives all users READ permission. When you apply | |
| 93 this to an object, anyone on the Internet can | |
| 94 read the object without authenticating. | |
| 95 | |
| 96 public-read-write Gives the requester FULL_CONTROL permission and | |
| 97 gives all users READ and WRITE permission. This | |
| 98 ACL applies only to buckets. | |
| 99 | |
| 100 authenticated-read Gives the requester FULL_CONTROL permission and | |
| 101 gives all authenticated Google account holders | |
| 102 READ permission. | |
| 103 | |
| 104 bucket-owner-read Gives the requester FULL_CONTROL permission and | |
| 105 gives the bucket owner READ permission. This is | |
| 106 used only with objects. | |
| 107 | |
| 108 bucket-owner-full-control Gives the requester FULL_CONTROL permission and | |
| 109 gives the bucket owner FULL_CONTROL | |
| 110 permission. This is used only with objects. | |
| 111 | |
| 112 | |
| 113 <B>ACL XML</B> | |
| 114 When you use a canned ACL, it is translated into an XML representation | |
| 115 that can later be retrieved and edited to specify more fine-grained | |
| 116 detail about who can read and write buckets and objects. By running | |
| 117 the gsutil getacl command you can retrieve the ACL XML, and edit it to | |
| 118 customize the permissions. | |
| 119 | |
| 120 As an example, if you create an object in a bucket that has no default | |
| 121 object ACL set and then retrieve the ACL on the object, it will look | |
| 122 something like this: | |
| 123 | |
| 124 <AccessControlList> | |
| 125 <Owner> | |
| 126 <ID> | |
| 127 00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7 | |
| 128 </ID> | |
| 129 </Owner> | |
| 130 <Entries> | |
| 131 <Entry> | |
| 132 <Scope type="GroupById"> | |
| 133 <ID> | |
| 134 00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7 | |
| 135 </ID> | |
| 136 </Scope> | |
| 137 <Permission> | |
| 138 FULL_CONTROL | |
| 139 </Permission> | |
| 140 </Entry> | |
| 141 <Entry> | |
| 142 <Scope type="GroupById"> | |
| 143 <ID> | |
| 144 00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51 | |
| 145 </ID> | |
| 146 </Scope> | |
| 147 <Permission> | |
| 148 FULL_CONTROL | |
| 149 </Permission> | |
| 150 </Entry> | |
| 151 <Entry> | |
| 152 <Scope type="GroupById"> | |
| 153 <ID> | |
| 154 00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71 | |
| 155 </ID> | |
| 156 </Scope> | |
| 157 <Permission> | |
| 158 READ | |
| 159 </Permission> | |
| 160 </Entry> | |
| 161 </Entries> | |
| 162 </AccessControlList> | |
| 163 | |
| 164 The ACL consists of an Owner element and a collection of Entry elements, | |
| 165 each of which specifies a Scope and a Permission. Scopes are the way you | |
| 166 specify an individual or group of individuals, and Permissions specify what | |
| 167 access they're permitted. | |
| 168 | |
| 169 This particular ACL grants FULL_CONTROL to two groups (which means members | |
| 170 of those groups are allowed to read the object and read and write the ACL), | |
| 171 and READ permission to a third group. The project groups are (in order) | |
| 172 the owners group, editors group, and viewers group. | |
| 173 | |
| 174 The 64 digit hex identifiers used in this ACL are called canonical IDs, | |
| 175 and are used to identify predefined groups associated with the project that | |
| 176 owns the bucket. For more information about project groups, see "gsutil | |
| 177 help projects". | |
| 178 | |
| 179 Here's an example of an ACL specified using the GroupByEmail and GroupByDomain | |
| 180 scopes: | |
| 181 | |
| 182 <AccessControlList> | |
| 183 <Entries> | |
| 184 <Entry> | |
| 185 <Permission> | |
| 186 FULL_CONTROL | |
| 187 </Permission> | |
| 188 <Scope type="GroupByEmail"> | |
| 189 <EmailAddress>travel-companion-owners@googlegroups.com</EmailAddress> | |
| 190 </Scope> | |
| 191 </Entry> | |
| 192 <Entry> | |
| 193 <Permission> | |
| 194 READ | |
| 195 </Permission> | |
| 196 <Scope type="GroupByDomain"> | |
| 197 <Domain>example.com</Domain> | |
| 198 </Scope> | |
| 199 </Entry> | |
| 200 </Entries> | |
| 201 </AccessControlList> | |
| 202 | |
| 203 This ACL grants members of an email group FULL_CONTROL, and grants READ | |
| 204 access to any user in a domain (which must be a Google Apps for Business | |
| 205 domain). By applying email group grants to a collection of objects | |
| 206 you can edit access control for large numbers of objects at once via | |
| 207 http://groups.google.com. That way, for example, you can easily and quickly | |
| 208 change access to a group of company objects when employees join and leave | |
| 209 your company (i.e., without having to individually change ACLs across | |
| 210 potentially millions of objects). | |
| 211 | |
| 212 | |
| 213 <B>SHARING SCENARIOS</B> | |
| 214 For more detailed examples how to achieve various useful sharing use | |
| 215 cases see https://developers.google.com/storage/docs/collaboration | |
| 216 """) | |
| 217 | |
| 218 | |
| 219 class CommandOptions(HelpProvider): | |
| 220 """Additional help about Access Control Lists.""" | |
| 221 | |
| 222 help_spec = { | |
| 223 # Name of command or auxiliary help info for which this help applies. | |
| 224 HELP_NAME : 'acls', | |
| 225 # List of help name aliases. | |
| 226 HELP_NAME_ALIASES : ['acl', 'ACL', 'access control', 'access control list', | |
| 227 'authorization', 'canned', 'canned acl'], | |
| 228 # Type of help: | |
| 229 HELP_TYPE : HelpType.ADDITIONAL_HELP, | |
| 230 # One line summary of this help. | |
| 231 HELP_ONE_LINE_SUMMARY : 'Working with Access Control Lists', | |
| 232 # The full help text. | |
| 233 HELP_TEXT : _detailed_help_text, | |
| 234 } | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2280023003:
depot_tools: Remove third_party/gsutil (Closed)
