vmkdir - Create a new directory in the Vesta repository
vmkdir [-q] [-Q] [-v] [-a] [-A] [-p] [-f] [-h hints] [-R repos] directory
In the most common usage, only the directory argument is given.
See the vesta-intro man page's Terminology section for definitions of terms, and its Name Interpretation section for an explanation of how names are looked up.
The vmkdir command creates a new directory in the Vesta repository. This provides an alternative to creating a directory with the normal mkdir command through the repository's NFS interface (which in some cases doesn't work depending on the quirks of different NFS client implementations). It also makes it possible to create a directory in a remote repository and acquire local mastership of it with one command.
You must have write access to the directory in which directory is to be placed. The newly created directory is owned by you, but has access permissions inherited from its parent directory.
In the presence of replication, the directory creation cannot always be carried out in the local repository. In particular, the local repository may not have the master copy of the parent directory. Also, the -a/-A flags control which repository vmkdir will give mastership of the created directory. (See vrepl(1) and vmaster(1) for more information about replication and mastership.)
If the parent directory is mastered locally, vmkdir creates the new directory in the local repository (and the -a/-A flags have no effect).
If the parent directory is not mastered locally, vmkdir may give mastership of directory to the local repository, if either the -a flag is specified or [UserInterface]vmkdir_acquires is set to true. In this case, it creates the directory remotely in the master copy, replicates it to the local repository, and transfers mastership.
If the -A flag is specified or [UserInterface]vmkdir_acquires is set to false and the parent directory is mastered remotely, vmkdir will leave mastership of the new directory with the master repository of its parent directory. It creates the directory remotely in the master copy and replicates it to the local repository.
Without the -f flag, vmkdir will refuse to create a directory anywhere inside a package or branch (that is, in any directory whose type attribute contains any of the following values: package, branch, checkout, session).
The -p flag is a convenience feature which causes vmkdir to give the created directory type "package-parent", which allows packages to be created as children of the new directory.
Creating a directory that is directly below the repository root (/vesta) is a special case (as there is no master copy of the repository root). To create such a top-level directory, you must be the special wizard user. Also, all top-level directories must be globally unique across all repositories in the universe in the past, present, or future. We strongly recommend that every name you create in this directory be an Internet domain name that belongs to you (or, failing that, an e-mail address with '@' changed to '_'); if everyone follows this convention, uniqueness is guaranteed. (See the vrepl(1) and repository(8) man pages for more information.) Before creating a top-level directory, vmkdir will remind you of this and ask for confirmation.
vmkdir returns status 0 for success, 1 for parameter syntax errors, or 2 for more serious errors. (Note that if any of the trigger commands fail, vmkdir returns status 2.)
- -q
- Quiet; suppress printing out what is being done.
- -Q
- Query; print out what the command would do, but don't do it.
- -h hints
- If vmkdir fails to find the master copy of the parent directory either the local repository or any of those repositories listed in [UserInterface]DefaultHints, you can suggest additional repositories for it to look in using this option. The hints argument is a comma- or space-separated list of repositories, specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.
- -R repos
- Create the directory in repos instead of the default local repository. The repository is specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.
- -a or -A
- Do (-a) or do not (-A) acquire mastership of the created directory when the local repository doesn't have mastership of the parent directory. The default is controlled by the [UserInterface]vmkdir_acquires configuration setting. (Note that if the parent directory of directory is mastered in the local repository, these flags have no effect.)
- -p
- Give the created directory the type "package-parent" (that is, a type attribute with this value). This allows packages to be created as children of the new directory. (See the vcreate(1) man page for more information.)
- -f
- Force; omit sanity checking. If the -f flag is not given, the new directory's parent may not be any part of a package or branch (that is, a directory with a type attribute that contains any of the following values: package, branch, checkout, session).
- -v
- Displays extra information about triggers. Before executing any trigger commands, the environment variables used to provide information to them are printed. Also, each trigger setting is printed before the command is executed. This can be used to help debug trigger problems. When used with the query flag (-Q), the triggers are displayed in their sorted order without actually running them.
The following values are obtained from the [UserInterface] section of the Vesta configuration file (vesta.cfg).
- AppendableRootName
- The filename under which the global root directory of Vesta repositories is mounted. Ordinarily set to /vesta.
- MutableRootName
- The filename under which the local tree of mutable directories provided by Vesta is mounted. Ordinarily set to /vesta-work.
- realm
- Global user names are formed by appending @realm to the local name. This setting is optional. If it is not set, [Repository]realm is used.
- TimeFormat
- A format string for strftime(3) to produce time strings for Vesta attributes. A common setting is "%a %b %e %T %Z %Y".
- vmkdir_acquires
- Sets the default policy for which repository should have mastership of the created directory when the master repository of the parent directory is remote. If it is equal (witout regard to case) to "yes", "on", or "true", or can be parsed as an integer that is non-zero, the local repository will acquire mastership (as if the -a flag had been given). If it is equal (witout regard to case) to "no", "off", or "false", or can be parsed as an integer that is zero, the master repository of the parent directory will retain mastership of the created directory (as if the -A flag had been given). If not set, defaults to "false".
- DefaultHints
- A comma- or space-separated list of additional repositories to search for the master copy of an object. Each repository is specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port. This setting is optional.
The following values are obtained from the [Repository] section of the Vesta configuration file.
- VestaSourceSRPC_host
- The host name of the default (local) repository.
- VestaSourceSRPC_port
- The default TCP port number for repositories.
- realm
- Global user names are formed by appending @realm to the local name. This setting is only used if [UserInterface]realm is not set.
The following value is obtained from the [Run_Tool] section of the Vesta configuration file.
- VolatileRootName
- The mount point used for temporary directories used during tool invocations. Attempting to create a directory inside the volatile root (which is often below the mutable root) is considered an error.
Settings in the [vmkdir pre trigger] and [vmkdir post trigger] sections of the configuration file are used as commands to be run before and after the repository is modified. See the next section.
Users can configure commands in the Vesta configuration file (vesta.cfg) to be executed before and after vmkdir modifies the repository. Each setting in the [vmkdir pre trigger] section specifies a command to be run before any action is taken, and each setting in the [vmkdir post trigger] section specifies a command to be run after all actions are complete.
The value of each setting specifies a command to run. The names of the settings define the order in which these commands are run. The setting names are sorted as strings, but comparing embedded sequences of digits as decimal integers. (So, for example "foo_10_bar" will sort after "foo_2_bar".) The suggested naming convention for trigger settings is to start with an integer, follow with a descriptive name, and follow that with any other text. (This is based on the convention used for System V style init script links typically stored in /etc/rcN.d.)
Here's a simple example of how we suggest naming trigger settings, and how they are ordered for execution:
[vmkdir pre trigger] 100world = echo World! 9tada = echo Tada: 50hello = echo Hello,Because these all start with numbers, they will be executed in the order "9tada", "50hello", "100world". The output will look like this:% vmkdir /vesta/example.com/... Tada: Hello, World! Creating directory /vesta/example.com/...Trigger commands are executed with system(3). On most operating systems this means "/bin/sh -c command", so simple in-line shell scripts can be used. (Note that each is executed in its own shell process, so environment variables set during one trigger command will not propagate to subsequent ones.)If any of the commands in the [vmkdir pre trigger] section exit with error (non-zero) status or are terminated by a signal (e.g. segmentation fault, abort), vmkdir will exit without creating a directory.
The commands in the [vmkdir post trigger] section will only be executed if a new directory is successfully created. If vmkdir fails with an error, the commands in the [vmkdir post trigger] section will not be executed.
Note that all the trigger commands (both pre and post) are executed sequentially. Once a trigger command is started, nothing else happens until it completes. If any of the pre trigger commands runs forever, vmkdir will not create a directory. If any of the post trigger commands runs forever, vmkdir will not complete. (In other words, a trigger command that hangs will cause vmkdir to hang.) If any of the pre or post trigger commands exit with error status or are terminated by a signal, vmkdir will exit without running any more commands from those sections. (In other words, a trigger command that fails will prevent further trigger commands from being run.)
If the the query flag (-Q) is given, the trigger commands will not actually be run.
Information about what vmkdir is going to do or has just done is provided to the trigger commands through the following environment variables:
- VESTA_TOOL
- The name of the Vesta tool the trigger command has been invoked from. (For vmkdir, this will always be "vmkdir".)
- VESTA_REPOS
- The local repository (host:port) vmkdir communicates with (either the default from the configuration file or the one specified with the -R flag.
- VESTA_MASTER_HINTS
- Additional repositories which may have been consulted in order to find the master copy of the parent directory. This is the combination of the argument to the -h flag (if it was used) and the hints from the [UserInterface]DefaultHints configuration setting (if set in the configuration file).
- VESTA_MASTER_REMOTE
- Set to 1 if the parent directory of the directory created by vmkdir is mastered in a remote repository, set to 0 otherwise. If this is set to 1, the directory will be created in the remote master ($VESTA_MASTER_REPOS) and replicated to the local repository ($VESTA_REPOS).
- VESTA_MASTER_REPOS
- The repository (host:port) with mastership of the parent directory of the directory created by vmkdir. If this is different from $VESTA_REPOS, $VESTA_MASTER_REMOTE will be set to 1 and the directory is created at the remote master repository.
- VESTA_DIR
- The directory created by vmkdir.
- VESTA_ACQUIRE_MASTERSHIP
- Set to 1 if vmkdir is creating a directory at a remote master repository and acquiring mastership of it in the local repository, set to 0 otherwise. (If $VESTA_REPOS is the same as $VESTA_MASTER_REPOS this will be 0.) See the description of the -a/-A flags above.
- VESTA_PACKAGE_PARENT
- Set to 1 if the -p flag was given and the directory is being created under /vesta, set to 0 otherwise. (This will be 0 if the directory being created is under /vesta-work, even if the -p flag was given.)
- VESTA_QUIET
- Set to 1 if the quiet flag (-q) was given, set to 0 otherwise.
- VESTA_FORCE
- Set to 1 if the force flag (-f) was given, set to 0 otherwise.
(Note that the environment variables are the same for both the pre and post trigger commands.)
Here are some examples using these environment variables:
[vmkdir pre trigger] // If the user tries to create a directory with type package-parent // directly below /vesta, cause vmkdir to fail 50no_toplevel_pp = if [ "`dirname $VESTA_DIR`" = "/vesta" -a $VESTA_PACKAGE_PARENT -eq 1 ]; then exit 1; fi [vmkdir post trigger] // Add an attribute when a directory is created remotely and has local // mastership acquired 50made_remote = [ $VESTA_ACQUIRE_MASTERSHIP -eq 0 ] || vattrib -R $VESTA_REPOS -s "created-at" $VESTA_MASTER_REPOS $VESTA_DIRIf the verbose trigger flag (-v) is given, these environment variables will be printed, and each trigger command will be printed before executing it. This can be useful for debugging trigger problems. If both verbose trigger flag and the the query flag (-Q) are given, the triggers are displayed in their sorted order without actually running them. This can be used to find out what trigger commands are configured without actually running them.
vmkdir is atomic if it modifies only the local repository. If a remote repository must be modified, however, the action performed at each repository is individually atomic, but vmkdir can die between the actions on the remote and local repositories. To make this problem less likely to occur, vmkdir ignores SIGINT (the ^C interrupt) during the critical section.
vesta-intro(1), repos-ui(1) vcreate(1) vrepl(1) repository(8)
This page was generated automatically by mtex software.Ken Schalk <ken@xorian.net>
(Derived from vcreate, written by Tim Mann.)