tools/telemetry/third_party/gsutilz/gslib/addlhelp/naming.py

   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   )