1 # -*- coding: utf-8 -*- 2 # Copyright 2012 Google Inc. All Rights Reserved. 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 """Additional help about gsutil object and bucket naming.""" 16 17 from __future__ import absolute_import 18 19 from gslib.help_provider import HelpProvider 20 21 _DETAILED_HELP_TEXT = (""" 22 <B>BUCKET NAME REQUIREMENTS</B> 23 Google Cloud Storage has a single namespace, so you will not be allowed 24 to create a bucket with a name already in use by another user. You can, 25 however, carve out parts of the bucket name space corresponding to your 26 company's domain name (see "DOMAIN NAMED BUCKETS"). 27 28 Bucket names must conform to standard DNS naming conventions. This is 29 because a bucket name can appear in a DNS record as part of a CNAME 30 redirect. In addition to meeting DNS naming requirements, Google Cloud 31 Storage imposes other requirements on bucket naming. At a minimum, your 32 bucket names must meet the following requirements: 33 34 - Bucket names must contain only lowercase letters, numbers, dashes (-), and 35 dots (.). 36 37 - Bucket names must start and end with a number or letter. 38 39 - Bucket names must contain 3 to 63 characters. Names containing dots can 40 contain up to 222 characters, but each dot-separated component can be 41 no longer than 63 characters. 42 43 - Bucket names cannot be represented as an IPv4 address in dotted-decimal 44 notation (for example, 192.168.5.4). 45 46 - Bucket names cannot begin with the "goog" prefix. 47 48 - For DNS compliance, you should not have a period adjacent to another 49 period or dash. For example, ".." or "-." or ".-" are not acceptable. 50 51 52 <B>OBJECT NAME REQUIREMENTS</B> 53 Object names can contain any sequence of Unicode characters, of length 1-1024 54 bytes when UTF-8 encoded. Object names must not contain CarriageReturn, 55 CarriageReturnLineFeed, or the XML-disallowed surrogate blocks (xFFFE 56 or xFFFF). 57 58 We strongly recommend that you abide by the following object naming 59 conventions: 60 61 - Avoid using control characters that are illegal in XML 1.0 in your object 62 names (#x7F-#x84 and #x86-#x9F). These characters will cause XML listing 63 issues when you try to list your objects. 64 65 - Avoid using "#" in your object names. gsutil interprets object names ending 66 with #<numeric string> as version identifiers, so including "#" in object 67 names can make it difficult or impossible to perform various operations on 68 such objects using gsutil (see 'gsutil help versions'). 69 70 - Avoid using "[", "]", "*", or "?" in your object names. gsutil interprets 71 these characters as wildcards, so including any of these characters in 72 object names can make it difficult or impossible to perform various wildcard 73 operations using gsutil (see 'gsutil help wildcards'). 74 75 See also 'gsutil help encoding' about file/object name encoding requirements 76 and potential interoperability concerns. 77 78 79 <B>DOMAIN NAMED BUCKETS</B> 80 You can carve out parts of the Google Cloud Storage bucket name space 81 by creating buckets with domain names (like "example.com"). 82 83 Before you can create a bucket name containing one or more '.' characters, 84 the following rules apply: 85 86 - If the name is a syntactically valid DNS name ending with a 87 currently-recognized top-level domain (such as .com), you will be required 88 to verify domain ownership. 89 - Otherwise you will be disallowed from creating the bucket. 90 91 If your project needs to use a domain-named bucket, you need to have 92 a team member both verify the domain and create the bucket. This is 93 because Google Cloud Storage checks for domain ownership against the 94 user who creates the bucket, so the user who creates the bucket must 95 also be verified as an owner or manager of the domain. 96 97 To verify as the owner or manager of a domain, use the Google Webmaster 98 Tools verification process. The Webmaster Tools verification process 99 provides three methods for verifying an owner or manager of a domain: 100 101 1. Adding a special Meta tag to a site's homepage. 102 2. Uploading a special HTML file to a site. 103 3. Adding a DNS TXT record to a domain's DNS configuration. 104 105 Meta tag verification and HTML file verification are easier to perform and 106 are probably adequate for most situations. DNS TXT record verification is 107 a domain-based verification method that is useful in situations where a 108 site wants to tightly control who can create domain-named buckets. Once 109 a site creates a DNS TXT record to verify ownership of a domain, it takes 110 precedence over meta tag and HTML file verification. For example, you might 111 have two IT staff members who are responsible for managing your site, called 112 "example.com." If they complete the DNS TXT record verification, only they 113 would be able to create buckets called "example.com", "reports.example.com", 114 "downloads.example.com", and other domain-named buckets. 115 116 Site-Based Verification 117 ----------------------- 118 119 If you have administrative control over the HTML files that make up a site, 120 you can use one of the site-based verification methods to verify that you 121 control or own a site. When you do this, Google Cloud Storage lets you 122 create buckets representing the verified site and any sub-sites - provided 123 nobody has used the DNS TXT record method to verify domain ownership of a 124 parent of the site. 125 126 As an example, assume that nobody has used the DNS TXT record method to verify 127 ownership of the following domains: abc.def.example.com, def.example.com, 128 and example.com. In this case, Google Cloud Storage lets you create a bucket 129 named abc.def.example.com if you verify that you own or control any of the 130 following sites: 131 132 http://abc.def.example.com 133 http://def.example.com 134 http://example.com 135 136 Domain-Based Verification 137 ------------------------- 138 139 If you have administrative control over a domain's DNS configuration, you can 140 use the DNS TXT record verification method to verify that you own or control a 141 domain. When you use the domain-based verification method to verify that you 142 own or control a domain, Google Cloud Storage lets you create buckets that 143 represent any subdomain under the verified domain. Furthermore, Google Cloud 144 Storage prevents anybody else from creating buckets under that domain unless 145 you add their name to the list of verified domain owners or they have verified 146 their domain ownership by using the DNS TXT record verification method. 147 148 For example, if you use the DNS TXT record verification method to verify your 149 ownership of the domain example.com, Google Cloud Storage will let you create 150 bucket names that represent any subdomain under the example.com domain, such 151 as abc.def.example.com, example.com/music/jazz, or abc.example.com/music/jazz. 152 153 Using the DNS TXT record method to verify domain ownership supersedes 154 verification by site-based verification methods. For example, if you 155 use the Meta tag method or HTML file method to verify domain ownership 156 of http://example.com, but someone else uses the DNS TXT record method 157 to verify ownership of the example.com domain, Google Cloud Storage will 158 not allow you to create a bucket named example.com. To create the bucket 159 example.com, the domain owner who used the DNS TXT method to verify domain 160 ownership must add you to the list of verified domain owners for example.com. 161 162 The DNS TXT record verification method is particularly useful if you manage 163 a domain for a large organization that has numerous subdomains because it 164 lets you control who can create buckets representing those domain names. 165 166 Note: If you use the DNS TXT record verification method to verify ownership of 167 a domain, you cannot create a CNAME record for that domain. RFC 1034 disallows 168 inclusion of any other resource records if there is a CNAME resource record 169 present. If you want to create a CNAME resource record for a domain, you must 170 use the Meta tag verification method or the HTML file verification method. 171 """) 172 173 174 class CommandOptions(HelpProvider): 175 """Additional help about gsutil object and bucket naming.""" 176 177 # Help specification. See help_provider.py for documentation. 178 help_spec = HelpProvider.HelpSpec( 179 help_name='naming', 180 help_name_aliases=['domain', 'limits', 'name', 'names'], 181 help_type='additional_help', 182 help_one_line_summary='Object and Bucket Naming', 183 help_text=_DETAILED_HELP_TEXT, 184 subcommand_help_text={}, 185 ) 186
