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>BUCKET NAME REQUIREMENTS</B> | |
25 Google Cloud Storage has a single namespace, so you will not be allowed | |
26 to create a bucket with a name already in use by another user. You can, | |
27 however, carve out parts of the bucket name space corresponding to your | |
28 company's domain name (see "DOMAIN NAMED BUCKETS"). | |
29 | |
30 Bucket names must conform to standard DNS naming conventions. This is | |
31 because a bucket name can appear in a DNS record as part of a CNAME | |
32 redirect. In addition to meeting DNS naming requirements, Google Cloud | |
33 Storage imposes other requirements on bucket naming. At a minimum, your | |
34 bucket names must meet the following requirements: | |
35 | |
36 - Bucket names must contain only lowercase letters, numbers, dashes (-), and | |
37 dots (.). | |
38 | |
39 - Bucket names must start and end with a number or letter. | |
40 | |
41 - Bucket names must contain 3 to 63 characters. Names containing dots can | |
42 contain up to 222 characters, but each dot-separated component can be | |
43 no longer than 63 characters. | |
44 | |
45 - Bucket names cannot be represented as an IPv4 address in dotted-decimal | |
46 notation (for example, 192.168.5.4). | |
47 | |
48 - Bucket names cannot begin with the "goog" prefix. | |
49 | |
50 - For DNS compliance, you should not have a period adjacent to another | |
51 period or dash. For example, ".." or "-." or ".-" are not acceptable. | |
52 | |
53 | |
54 <B>OBJECT NAME REQUIREMENTS</B> | |
55 Object names can contain any sequence of Unicode characters, of length 1-1024 | |
56 bytes when UTF-8 encoded. Object names must not contain CarriageReturn, | |
57 CarriageReturnLineFeed, or the XML-disallowed surrogate blocks (xFFFE | |
58 or xFFFF). | |
59 | |
60 We highly recommend that you avoid using control characters that are illegal | |
61 in XML 1.0 in your object names. These characters will cause XML listing | |
62 issues when you try to list your objects. | |
63 | |
64 | |
65 <B>DOMAIN NAMED BUCKETS</B> | |
66 You can carve out parts of the Google Cloud Storage bucket name space | |
67 by creating buckets with domain names (like "example.com"). | |
68 | |
69 Before you can create a bucket name containing one or more '.' characters, | |
70 the following rules apply: | |
71 - If the name is a syntactically valid DNS name ending with a | |
72 currently-recognized top-level domain (such as .com), you will be required | |
73 to verify domain ownership. | |
74 - Otherwise you will be disallowed from creating the bucket. | |
75 | |
76 If your project needs to use a domain-named bucket, you need to have | |
77 a team member both verify the domain and create the bucket. This is | |
78 because Google Cloud Storage checks for domain ownership against the | |
79 user who creates the bucket, so the user who creates the bucket must | |
80 also be verified as an owner or manager of the domain. | |
81 | |
82 To verify as the owner or manager of a domain, use the Google Webmaster | |
83 Tools verification process. The Webmaster Tools verification process | |
84 provides three methods for verifying an owner or manager of a domain: | |
85 | |
86 1. Adding a special Meta tag to a site's homepage. | |
87 2. Uploading a special HTML file to a site. | |
88 3. Adding a DNS TXT record to a domain's DNS configuration. | |
89 | |
90 Meta tag verification and HTML file verification are easier to perform and | |
91 are probably adequate for most situations. DNS TXT record verification is | |
92 a domain-based verification method that is useful in situations where a | |
93 site wants to tightly control who can create domain-named buckets. Once | |
94 a site creates a DNS TXT record to verify ownership of a domain, it takes | |
95 precedence over meta tag and HTML file verification. For example, you might | |
96 have two IT staff members who are responsible for managing your site, called | |
97 "example.com." If they complete the DNS TXT record verification, only they | |
98 would be able to create buckets called "example.com", "reports.example.com", | |
99 "downloads.example.com", and other domain-named buckets. | |
100 | |
101 Site-Based Verification | |
102 | |
103 If you have administrative control over the HTML files that make up a site, | |
104 you can use one of the site-based verification methods to verify that you | |
105 control or own a site. When you do this, Google Cloud Storage lets you | |
106 create buckets representing the verified site and any sub-sites - provided | |
107 nobody has used the DNS TXT record method to verify domain ownership of a | |
108 parent of the site. | |
109 | |
110 As an example, assume that nobody has used the DNS TXT record method to verify | |
111 ownership of the following domains: abc.def.example.com, def.example.com, | |
112 and example.com. In this case, Google Cloud Storage lets you create a bucket | |
113 named abc.def.example.com if you verify that you own or control any of the | |
114 following sites: | |
115 | |
116 http://abc.def.example.com | |
117 http://def.example.com | |
118 http://example.com | |
119 | |
120 Domain-Based Verification | |
121 | |
122 If you have administrative control over a domain's DNS configuration, you can | |
123 use the DNS TXT record verification method to verify that you own or control a | |
124 domain. When you use the domain-based verification method to verify that you | |
125 own or control a domain, Google Cloud Storage lets you create buckets that | |
126 represent any subdomain under the verified domain. Furthermore, Google Cloud | |
127 Storage prevents anybody else from creating buckets under that domain unless | |
128 you add their name to the list of verified domain owners or they have verified | |
129 their domain ownership by using the DNS TXT record verification method. | |
130 | |
131 For example, if you use the DNS TXT record verification method to verify your | |
132 ownership of the domain example.com, Google Cloud Storage will let you create | |
133 bucket names that represent any subdomain under the example.com domain, such | |
134 as abc.def.example.com, example.com/music/jazz, or abc.example.com/music/jazz. | |
135 | |
136 Using the DNS TXT record method to verify domain ownership supersedes | |
137 verification by site-based verification methods. For example, if you | |
138 use the Meta tag method or HTML file method to verify domain ownership | |
139 of http://example.com, but someone else uses the DNS TXT record method | |
140 to verify ownership of the example.com domain, Google Cloud Storage will | |
141 not allow you to create a bucket named example.com. To create the bucket | |
142 example.com, the domain owner who used the DNS TXT method to verify domain | |
143 ownership must add you to the list of verified domain owners for example.com. | |
144 | |
145 The DNS TXT record verification method is particularly useful if you manage | |
146 a domain for a large organization that has numerous subdomains because it | |
147 lets you control who can create buckets representing those domain names. | |
148 | |
149 Note: If you use the DNS TXT record verification method to verify ownership of | |
150 a domain, you cannot create a CNAME record for that domain. RFC 1034 disallows | |
151 inclusion of any other resource records if there is a CNAME resource record | |
152 present. If you want to create a CNAME resource record for a domain, you must | |
153 use the Meta tag verification method or the HTML file verification method. | |
154 | |
155 | |
156 """) | |
157 | |
158 | |
159 class CommandOptions(HelpProvider): | |
160 """Additional help about gsutil object and bucket naming.""" | |
161 | |
162 help_spec = { | |
163 # Name of command or auxiliary help info for which this help applies. | |
164 HELP_NAME : 'naming', | |
165 # List of help name aliases. | |
166 HELP_NAME_ALIASES : ['domain', 'limits', 'name', 'names'], | |
167 # Type of help: | |
168 HELP_TYPE : HelpType.ADDITIONAL_HELP, | |
169 # One line summary of this help. | |
170 HELP_ONE_LINE_SUMMARY : 'Object and bucket naming', | |
171 # The full help text. | |
172 HELP_TEXT : _detailed_help_text, | |
173 } | |
OLD | NEW |