X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Ftmpfiles.d.xml;h=67bd1dc7243b9851e4c68b61e3daa192396b2c0e;hb=f789e0b4f891800557c74c385d0f61a0164cb16f;hp=ed119ad86aec733f6cff230ea5810e413b88f72f;hpb=11a15892230011c331d4e31cdbbd58e8b3dfe4af;p=thirdparty%2Fsystemd.git diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index ed119ad86ae..67bd1dc7243 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -1,26 +1,16 @@ - - + + tmpfiles.d systemd - - - - Documentation - Brandon - Philips - brandon@ifup.org - - @@ -51,25 +41,33 @@ Description - systemd-tmpfiles uses the configuration - files from the above directories to describe the creation, - cleaning and removal of volatile and temporary files and - directories which usually reside in directories such as - /run or /tmp. - - Volatile and temporary files and directories are those - located in /run (and its alias - /var/run), /tmp, - /var/tmp, the API file systems such as - /sys or /proc, as well - as some other directories below /var. - - System daemons frequently require private runtime - directories below /run to place communication - sockets and similar in. For these, consider declaring them in - their unit files using RuntimeDirectory= (see - systemd.exec5 - for details), if this is feasible. + tmpfiles.d configuration files provide a generic mechanism to define the + creation of regular files, directories, pipes, and device nodes, adjustments to + their access mode, ownership, attributes, quota assignments, and contents, and + finally their time-based removal. It is mostly commonly used for volatile and + temporary files and directories (such as those located under /run, + /tmp, /var/tmp, the API file systems such as + /sys or /proc, as well as some other directories below + /var). + + systemd-tmpfiles uses this configuration to create volatile files and + directories during boot and to do periodic cleanup afterwards. See + systemd-tmpfiles5 for + the description of systemd-tmpfiles-setup.service, + systemd-tmpfiles-cleanup.service, and associated units. + + System daemons frequently require private runtime directories below /run to + store communication sockets and similar. For these, is is better to use + RuntimeDirectory= in their unit files (see + systemd.exec5 for + details), if the flexibility provided by tmpfiles.d is not required. The advantages + are that the configuration required by the unit is centralized in one place, and that the lifetime of the + directory is tied to the lifetime of the service itself. Similarly, StateDirectory=, + CacheDirectory=, LogsDirectory=, and + ConfigurationDirectory= should be used to create directories under + /var/lib/, /var/cache/, /var/log/, and + /etc/. tmpfiles.d should be used for files whose lifetime is + independent of any service or requires more complicated configuration. @@ -81,28 +79,20 @@ The second variant should be used when it is desirable to make it easy to override just this part of configuration. - Files in /etc/tmpfiles.d override files - with the same name in /usr/lib/tmpfiles.d and - /run/tmpfiles.d. Files in - /run/tmpfiles.d override files with the same - name in /usr/lib/tmpfiles.d. Packages should - install their configuration files in - /usr/lib/tmpfiles.d. Files in - /etc/tmpfiles.d are reserved for the local - administrator, who may use this logic to override the - configuration files installed by vendor packages. All - configuration files are sorted by their filename in lexicographic - order, regardless of which of the directories they reside in. If - multiple files specify the same path, the entry in the file with - the lexicographically earliest name will be applied. All other - conflicting entries will be logged as errors. When two lines are - prefix and suffix of each other, then the prefix is always - processed first, the suffix later. Lines that take globs are - applied after those accepting no globs. If multiple operations - shall be applied on the same file, (such as ACL, xattr, file - attribute adjustments), these are always done in the same fixed - order. Otherwise, the files/directories are processed in the order - they are listed. + Files in /etc/tmpfiles.d override files with the same name in + /usr/lib/tmpfiles.d and /run/tmpfiles.d. Files in + /run/tmpfiles.d override files with the same name in + /usr/lib/tmpfiles.d. Packages should install their configuration files in + /usr/lib/tmpfiles.d. Files in /etc/tmpfiles.d are reserved for the local + administrator, who may use this logic to override the configuration files installed by vendor packages. All + configuration files are sorted by their filename in lexicographic order, regardless of which of the directories + they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest + name will be applied. All other conflicting entries will be logged as errors. When two lines are prefix path and + suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies + to the line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are + applied after those accepting no globs. If multiple operations shall be applied on the same file (such as ACL, + xattr, file attribute adjustments), these are always done in the same fixed order. Except for those cases, the + files/directories are processed in the order they are listed. If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink @@ -117,9 +107,9 @@ The configuration format is one line per path containing type, path, mode, ownership, age, and argument fields: - #Type Path Mode UID GID Age Argument -d /run/user 0755 root root 10d - -L /tmp/foobar - - - - /dev/null + #Type Path Mode User Group Age Argument +d /run/user 0755 root root 10d - +L /tmp/foobar - - - - /dev/null Fields may be enclosed within quotes and contain C-style escapes. @@ -127,7 +117,7 @@ L /tmp/foobar - - - - /dev/null Type The type consists of a single letter and optionally an - exclamation mark. + exclamation mark and/or minus sign. The following line types are understood: @@ -157,107 +147,88 @@ L /tmp/foobar - - - - /dev/null d - Create a directory. The mode and ownership will be adjusted if - specified and the directory already exists. Contents of this directory are subject - to time based cleanup if the age argument is specified. + Create a directory. The mode and ownership will be adjusted if specified. Contents + of this directory are subject to time based cleanup if the age argument is specified. + D - Similar to d, but in addition the contents - of the directory will be removed when is used. - + Similar to d, but in addition the contents of the directory will + be removed when is used. e - Similar to d, but the directory will not be created if - it does not exist. Lines of this type accept shell-style globs in place of normal path - names. For this entry to be useful, at least one of the mode, uid, gid, or age arguments - must be specified, since otherwise this entry has no effect. If the age argument is - 0, contents of the directory will be unconditionally deleted every time - systemd-tmpfiles --clean is run. This can be useful when combined with - !, see the examples. + Adjust the mode and ownership of existing directories and remove their contents + based on age. + Lines of this type accept shell-style globs in place of normal path names. Contents of the + directories are subject to time based cleanup if the age argument is specified. If the age argument + is 0, contents will be unconditionally deleted every time + systemd-tmpfiles --clean is run. + + For this entry to be useful, at least one of the mode, user, group, or age arguments must be + specified, since otherwise this entry has no effect. As an exception, an entry with no effect may + be useful when combined with !, see the examples. v - Create a subvolume if the path does not - exist yet, the file system supports subvolumes (btrfs), and - the system itself is installed into a subvolume - (specifically: the root directory / is - itself a subvolume). Otherwise, create a normal directory, in - the same way as d. A subvolume created - with this line type is not assigned to any higher-level - quota group. For that, use q or - Q, which allow creating simple quota - group hierarchies, see below. + Create a subvolume if the path does not exist yet, the file system supports + subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root + directory / is itself a subvolume). Otherwise, create a normal directory, in + the same way as d. + + A subvolume created with this line type is not assigned to any higher-level quota group. For + that, use q or Q, which allow creating simple quota group + hierarchies, see below. q - Similar to v. However, - makes sure that the subvolume will be assigned to the same - higher-level quota groups as the subvolume it has been - created in. This ensures that higher-level limits and - accounting applied to the parent subvolume also include the - specified subvolume. On non-btrfs file systems, this line - type is identical to d. If the subvolume - already exists and is already assigned to one or more higher - level quota groups, no change to the quota hierarchy is - made. Also see Q below. See btrfs-qgroup8 - for details about the btrfs quota group - concept. + Create a subvolume or directory the same as v, but assign the + subvolume to the same higher-level quota groups as the parent. This ensures that higher-level + limits and accounting applied to the parent subvolume also include the specified subvolume. On + non-btrfs file systems, this line type is identical to d. + + If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the + subvolume is already attached to a quota group or not. Also see Q below. See btrfs-qgroup8 for + details about the btrfs quota group concept. Q - Similar to q. However, - instead of copying the higher-level quota group assignments - from the parent as-is, the lowest quota group of the parent - subvolume is determined that is not the leaf quota - group. Then, an "intermediary" quota group is inserted that - is one level below this level, and shares the same ID part - as the specified subvolume. If no higher-level quota group - exists for the parent subvolume, a new quota group at level - 255 sharing the same ID as the specified subvolume is - inserted instead. This new intermediary quota group is then - assigned to the parent subvolume's higher-level quota - groups, and the specified subvolume's leaf quota group is - assigned to it. - - Effectively, this has a similar effect as - q, however introduces a new higher-level - quota group for the specified subvolume that may be used to - enforce limits and accounting to the specified subvolume and - children subvolume created within it. Thus, by creating - subvolumes only via q and - Q, a concept of "subtree quotas" is - implemented. Each subvolume for which Q - is set will get a "subtree" quota group created, and all - child subvolumes created within it will be assigned to - it. Each subvolume for which q is set - will not get such a "subtree" quota group, but it is ensured - that they are added to the same "subtree" quota group as their - immediate parents. - - It is recommended to use - Q for subvolumes that typically contain - further subvolumes, and where it is desirable to have - accounting and quota limits on all child subvolumes - together. Examples for Q are typically - /home or - /var/lib/machines. In contrast, - q should be used for subvolumes that - either usually do not include further subvolumes or where no - accounting and quota limits are needed that apply to all - child subvolumes together. Examples for q - are typically /var or - /var/tmp. As with Q, - q has no effect on the quota group - hierarchy if the subvolume exists and already has at least - one higher-level quota group assigned. + Create the subvolume or directory the same as v, but assign the + new subvolume to a new leaf quota group. Instead of copying the higher-level quota group + assignments from the parent as is done with q, the lowest quota group of the + parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota + group is inserted that is one level below this level, and shares the same ID part as the specified + subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at + level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary + quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified + subvolume's leaf quota group is assigned to it. + + Effectively, this has a similar effect as q, however introduces a new higher-level + quota group for the specified subvolume that may be used to enforce limits and accounting to the specified + subvolume and children subvolume created within it. Thus, by creating subvolumes only via + q and Q, a concept of "subtree quotas" is implemented. Each subvolume + for which Q is set will get a "subtree" quota group created, and all child subvolumes + created within it will be assigned to it. Each subvolume for which q is set will not get + such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as + their immediate parents. + + It is recommended to use Q for subvolumes that typically contain further subvolumes, + and where it is desirable to have accounting and quota limits on all child subvolumes together. Examples for + Q are typically /home or /var/lib/machines. In + contrast, q should be used for subvolumes that either usually do not include further + subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes + together. Examples for q are typically /var or + /var/tmp. + + As with q, Q has no effect on the quota group hierarchy if the + subvolume already exists, regardless of whether the subvolume already belong to a quota group or not. + @@ -312,11 +283,11 @@ L /tmp/foobar - - - - /dev/null C Recursively copy a file or directory, if the - destination files or directories do not exist yet. Note that - this command will not descend into subdirectories if the - destination directory already exists. Instead, the entire - copy operation is skipped. If the argument is omitted, files - from the source directory + destination files or directories do not exist yet or the + destination directory is empty. Note that this command will not + descend into subdirectories if the destination directory already + exists and is not empty. Instead, the entire copy operation is + skipped. If the argument is omitted, files from the source directory /usr/share/factory/ with the same name are copied. Does not follow symlinks. @@ -363,20 +334,17 @@ L /tmp/foobar - - - - /dev/null z - Adjust the access mode, group and user, and - restore the SELinux security context of a file or directory, - if it exists. Lines of this type accept shell-style globs in - place of normal path names. Does not follow symlinks. + Adjust the access mode, user and group ownership, and restore the SELinux security + context of a file or directory, if it exists. Lines of this type accept shell-style globs in place + of normal path names. Does not follow symlinks. Z - Recursively set the access mode, group and - user, and restore the SELinux security context of a file or - directory if it exists, as well as of its subdirectories and - the files contained therein (if applicable). Lines of this - type accept shell-style globs in place of normal path - names. Does not follow symlinks. + Recursively set the access mode, user and group ownership, and restore the SELinux + security context of a file or directory if it exists, as well as of its subdirectories and the + files contained therein (if applicable). Lines of this type accept shell-style globs in place of + normal path names. Does not follow symlinks. @@ -400,15 +368,11 @@ L /tmp/foobar - - - - /dev/null Set file/directory attributes. Lines of this type accept shell-style globs in place of normal path names. - The format of the argument field is - [+-=][aAcCdDeijsStTu] . The prefix - + (the default one) causes the - attribute(s) to be added; - causes the - attribute(s) to be removed; = causes the - attributes to be set exactly as the following letters. The - letters aAcCdDeijsStTu select the new - attributes for the files, see - chattr + The format of the argument field is [+-=][aAcCdDeijPsStTu] . The prefix + + (the default one) causes the attribute(s) to be added; - + causes the attribute(s) to be removed; = causes the attributes to be set exactly + as the following letters. The letters aAcCdDeijPsStTu select the new attributes + for the files, see chattr 1 for further information. Passing only = as argument resets @@ -453,7 +417,7 @@ L /tmp/foobar - - - - /dev/null - If the exclamation mark is used, this line is only safe of + If the exclamation mark is used, this line is only safe to execute during boot, and can break a running system. Lines without the exclamation mark are presumed to be safe to execute at any time, e.g. on package upgrades. @@ -471,6 +435,15 @@ r! /tmp/.X[0-9]*-lock running system, and will only be executed with . + If the minus sign is used, this line failing to run + successfully during create (and only create) will not cause + the execution of systemd-tmpfiles to return + an error. + + For example: + # Modify sysfs but don't fail if we are in a container with a read-only /proc +w- /proc/sys/vm/swappiness - - - - 10 + Note that for all line types that result in creation of any kind of file node (i.e. f/F, d/D/v/q/Q, @@ -514,18 +487,14 @@ r! /tmp/.X[0-9]*-lock - UID, GID - - The user and group to use for this file or directory. This - may either be a numeric user/group ID or a user or group - name. If omitted or when set to -, the - default 0 (root) is used. For z and - Z lines, when omitted or when set to - -, the file ownership will not be - modified. These parameters are ignored for x, - r, R, - L, t, and - a lines. + User, Group + + The user and group to use for this file or directory. This may either be a numeric ID or a + user/group name. If omitted or when set to -, the user and group of the user who + invokes systemd-tmpfiles is used. For z and Z + lines, when omitted or when set to -, the file ownership will not be modified. These + parameters are ignored for x, r, R, + L, t, and a lines. @@ -573,6 +542,14 @@ r! /tmp/.X[0-9]*-lock (ctime). Any of these three (or two) values will prevent cleanup if it is more recent than the current time minus the age field. + + Note that while the aging algorithm is run a 'shared' BSD file lock (see flock2) is + taken on each directory the algorithm descends into (and each directory below that, and so on). If the + aging algorithm finds a lock is already taken on some directory, it (and everything below it) is + skipped. Applications may use this to temporarily exclude certain directory subtrees from the aging + algorithm: the applications can take a BSD file lock themselves, and as long as they keep it aging of + the directory and everything below it is disabled. @@ -611,60 +588,80 @@ r! /tmp/.X[0-9]*-lock - - %m - Machine ID - The machine ID of the running system, formatted as string. See machine-id5 for more information. - %b Boot ID The boot ID of the running system, formatted as string. See random4 for more information. + + %C + System or user cache directory + In mode, this is the same as $XDG_CACHE_HOME, and /var/cache otherwise. + + + %h + User home directory + This is the home directory of the user running the command. In case of the system instance this resolves to /root. + %H Host name The hostname of the running system. - %v - Kernel release - Identical to uname -r output. - - - %U - User UID - This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to 0. + %L + System or user log directory + In mode, this is the same as $XDG_CONFIG_HOME with /log appended, and /var/log otherwise. - %u - User name - This is the name of the user running the service manager instance. In case of the system manager this resolves to root. + %m + Machine ID + The machine ID of the running system, formatted as string. See machine-id5 for more information. - %h - User home directory - This is the home directory of the user running the service manager instance. In case of the system manager this resolves to /root. + %S + System or user state directory + In mode, this is the same as $XDG_CONFIG_HOME, and /var/lib otherwise. %t System or user runtime directory - In --user mode, this is the same $XDG_RUNTIME_DIR, and /run otherwise. + In mode, this is the same $XDG_RUNTIME_DIR, and /run otherwise. - %S - System or user state directory - In mode, this is the same as $XDG_CONFIG_HOME, and /var/lib otherwise. + %T + Directory for temporary files + This is either /tmp or the path $TMPDIR, $TEMP or $TMP are set to. - %C - System or user cache directory - In mode, this is the same as $XDG_CACHE_HOME, and /var/cache otherwise. + %g + User group + This is the name of the group running the command. In case of the system instance this resolves to root. - %L - System or user log directory - In mode, this is the same as $XDG_CONFIG_HOME with /log appended, and /var/log otherwise. + %G + User GID + This is the numeric GID of the group running the command. In case of the system instance this resolves to 0. + + + %u + User name + This is the name of the user running the command. In case of the system instance this resolves to root. + + + %U + User UID + This is the numeric UID of the user running the command. In case of the system instance this resolves to 0. + + + %v + Kernel release + Identical to uname -r output. + + + %V + Directory for larger and persistent temporary files + This is either /var/tmp or the path $TMPDIR, $TEMP or $TMP are set to. %% @@ -749,6 +746,13 @@ e! /var/cache/krb5rcache - - - 0 + + <filename>/run/</filename> and <filename>/var/run/</filename> + /var/run/ is a deprecated symlink to /run/, and + applications should use the latter. systemd-tmpfiles will warn if + /var/run/ is used. + + See Also