doc/man-pages/pod1/vos_create.pod.in

   1 =head1 NAME
   2
   3 vos_create - Creates a read/write volume and associated VLDB entry
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos create> S<<< B<-server> <I<machine name>> >>>
  11     S<<< B<-partition> <I<partition name>> >>>
  12     S<<< B<-name> <I<volume name>> >>>
  13     S<<< [B<-maxquota> <I<initial quota (KB)>>] >>>
  14     S<<< [B<-id> <I<volume id number>>] >>>
  15     S<<< [B<-roid> <I<RO volume id number>>] >>>
  16     S<<< [B<-cell> <I<cell name>>] >>>
  17     [B<-noauth>] [B<-localauth>] [B<-verbose>]
  18     [B<-encrypt>] [B<-noresolve>]
  19     S<<< [B<-config> <I<config directory>>] >>>
  20     [B<-help>]
  21
  22 B<vos cr> S<<< B<-s> <I<machine name>> >>> S<<< B<-p> <I<partition name>> >>>
  23     S<<< B<-na> <I<volume name>> >>> S<<< [B<-m> <I<initial quota>>] >>>
  24     S<<< [B<-i> <I<volume id number>>] >>>
  25     S<<< [B<-r> <I<RO volume id number>>] >>>
  26     S<<< [B<-c> <I<cell name>>] >>> [B<-noa>] [B<-l>] [B<-v>]
  27     [B<-e>] [B<-nor>]
  28     S<<< [B<-co> <I<config directory>>] >>>
  29     [B<-h>]
  30
  31 =for html
  32 </div>
  33
  34 =head1 DESCRIPTION
  35
  36 The B<vos create> command creates a read/write volume with the name
  37 specified by the B<-name> argument at the site specified by the B<-server>
  38 and B<-partition> arguments. In addition, the command allocates or sets
  39 the following:
  40
  41 =over 4
  42
  43 =item *
  44
  45 Volume ID numbers for the read/write volume and its associated read-only
  46 and backup volumes (this command does not actually create the latter two
  47 types of volume). A volume ID number is an identification number
  48 guaranteed to be unique within a cell.
  49
  50 =item *
  51
  52 An access control list (ACL) associated with the volume's root directory,
  53 which takes the same name as volume's mount point when the volume is
  54 mounted with the B<fs mkmount> command. An entry that grants all seven
  55 permissions to the members of the system:administrators group is
  56 automatically placed on the ACL. (In addition, the File Server by default
  57 always implicitly grants the C<l> (lookup) and C<a> (administer)
  58 permissions on every ACL to members of the system:administrators group,
  59 even when the group does not appear on an ACL; use the B<-implicit>
  60 argument to the B<fileserver> initialization command to alter the set of
  61 rights on a server-by-server basis if desired.)
  62
  63 =item *
  64
  65 The volume's space quota, set to 5000 kilobyte blocks by default. Use the
  66 B<-maxquota> argument to specify a different quota, or use the B<fs
  67 setquota> command to change the volume's quota after mounting the volume
  68 with the B<fs mkmount> command.
  69
  70 =back
  71
  72 The volume is empty when created. To access it via the Cache Manager,
  73 mount it in the file space by using the B<fs mkmount> command.
  74
  75 =head1 CAUTIONS
  76
  77 =include fragments/volsize-caution.pod
  78
  79 =head1 OPTIONS
  80
  81 =over 4
  82
  83 =item B<-server> <I<server name>>
  84
  85 Identifies the file server machine on which to create the read/write
  86 volume. Provide the machine's IP address or its host name (either fully
  87 qualified or using an unambiguous abbreviation). For details, see
  88 L<vos(1)>.
  89
  90 =item B<-partition> <I<partition name>>
  91
  92 Identifies the partition on which to create the read/write volume, on the
  93 file server machine specified by the B<-server> argument.  Provide the
  94 partition's complete name with preceding slash (for example, C</vicepa>)
  95 or use one of the three acceptable abbreviated forms. For details, see
  96 L<vos(1)>.
  97
  98 =item B<-name> <I<volume name>>
  99
 100 Specifies a name for the read/write volume. The maximum length is 22
 101 characters, which can include any alphanumeric or punctuation
 102 character. By convention, periods separate the fields in a name.  Do not
 103 apply the C<.backup> or C<.readonly> extension to a read/write volume
 104 name; they are reserved for the Volume Server to add to the read/write
 105 name when creating those backup and read-only volumes respectively.
 106
 107 =item B<-maxquota> <I<initial quota>>
 108
 109 Specifies the maximum amount of disk space the volume can use.  The size
 110 should be a positive integer followed by an optional suffix: C<K> for
 111 kibibytes (1024 bytes, the default), C<M> for mebibytes (1024 kibibytes),
 112 C<G> for gibibytes (1024 mebibytes), and C<T> for tebibytes (1024
 113 gibibytes).  The value C<0> (zero) grants an unlimited quota, but the size
 114 of the disk partition that houses the volume places an absolute limit on
 115 its size.  If this argument is omitted, the default value is C<5000K>.
 116
 117 =item B<-id> <I<volume ID>>
 118
 119 Specifies the volume ID for the read/write volume. If this options is not
 120 specified, or the given volume ID is 0, a volume ID will be allocated for
 121 the volume automatically. The volume IDs allocated should be fine for
 122 almost all cases, so you should almost never need to specify this option.
 123
 124 =item B<-roid> <I<readonly volume ID>>
 125
 126 Specifies the volume ID for the readonly volume corresponding to the
 127 read/write volume that is being created. The readonly volume will not be
 128 created; this merely specifies what volume ID the readonly volume will use
 129 when it is created. If a volume ID of 0 is specified here, no readonly
 130 volume ID will be assigned to the created volume immediately. A readonly
 131 volume ID can still be assigned later when B<vos addsite> is run; if a
 132 volume does not have a readonly volume ID associated with it by the time
 133 B<vos release> is run, a volume ID will be allocated for it.
 134
 135 If this option is not specified, the default readonly volume ID is one
 136 number higher than the read-write volume ID, whether or not that ID was
 137 manually specified.
 138
 139 As with the B<-id> option, the default allocated volume IDs should be
 140 sufficient for almost all cases, so you should almost never need to
 141 specify them explicitly. This option is available in OpenAFS
 142 versions 1.5.61 or later.
 143
 144 =item B<-cell> <I<cell name>>
 145
 146 Names the cell in which to run the command. Do not combine this argument
 147 with the B<-localauth> flag. For more details, see L<vos(1)>.
 148
 149 =item B<-noauth>
 150
 151 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 152 combine this flag with the B<-localauth> flag. For more details, see
 153 L<vos(1)>.
 154
 155 =item B<-localauth>
 156
 157 Constructs a server ticket using a key from the local
 158 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 159 to the Volume Server and Volume Location Server during mutual
 160 authentication. Do not combine this flag with the B<-cell> argument or
 161 B<-noauth> flag. For more details, see L<vos(1)>.
 162
 163 =item B<-verbose>
 164
 165 Produces on the standard output stream a detailed trace of the command's
 166 execution. If this argument is omitted, only warnings and error messages
 167 appear.
 168
 169 =item B<-encrypt>
 170
 171 Encrypts the command so that the operation's results are not transmitted
 172 across the network in clear text. This option is available in OpenAFS
 173 versions 1.4.11 or later and 1.5.60 or later.
 174
 175 =item B<-noresolve>
 176
 177 Shows all servers as IP addresses instead of the DNS name. This is very
 178 useful when the server address is registered as 127.0.0.1 or when dealing
 179 with multi-homed servers. This option is available in OpenAFS
 180 versions 1.4.8 or later and 1.5.35 or later.
 181
 182 =item B<-help>
 183
 184 Prints the online help for this command. All other valid options are
 185 ignored.
 186
 187 =back
 188
 189 =head1 OUTPUT
 190
 191 The Volume Server produces the following message to confirm that it
 192 created the volume:
 193
 194    Volume <volume_ID> created on partition <partition_name> of <machine_name>
 195
 196 =head1 EXAMPLES
 197
 198 The following command creates the read/write volume C<user.pat> on the
 199 F</vicepf> partition of the file server machine C<fs4.example.com>.
 200
 201    % vos create -server fs4.example.com -partition /vicepf -name user.pat
 202    Volume user.pat created on partition /vicepf of fs4.example.com
 203
 204 =head1 PRIVILEGE REQUIRED
 205
 206 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 207 machine specified with the B<-server> argument and on each database server
 208 machine. If the B<-localauth> flag is included, the issuer must instead be
 209 logged on to a server machine as the local superuser C<root>.
 210
 211 =head1 SEE ALSO
 212
 213 L<vos(1)>
 214
 215 =head1 COPYRIGHT
 216
 217 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 218
 219 This documentation is covered by the IBM Public License Version 1.0.  It was
 220 converted from HTML to POD by software written by Chas Williams and Russ
 221 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.