X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=598d31323f5f46f4c88ca72c2f7ad83049334706;hp=5a15e5ca05042031b7a8f37abd8c65f7064a9968;hb=99813a19122932da2cf55fecaf06446dcf7989a2;hpb=e93c33d4aadb41427f215d43545e7fadc6bcec6f diff --git a/man/systemctl.xml b/man/systemctl.xml index 5a15e5ca0..598d31323 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -21,7 +21,8 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> - + systemctl @@ -71,22 +72,6 @@ along with systemd; If not, see . The following options are understood: - - - - - Prints a short help - text and exits. - - - - - - - Prints a short version string and exits. - - - @@ -146,6 +131,18 @@ along with systemd; If not, see . + + + + + + When listing units, also show units of local + containers. Units of local containers will be prefixed with + the container name, separated by a single colon character + (:). + + + @@ -160,12 +157,27 @@ along with systemd; If not, see . + + + With list-dependencies, show the + units that are ordered before the specified unit. In other + words, list the units that are in the After= + directive of the specified unit, have the specified unit in + their Before= directive, or are otherwise + implicit dependencies of the specified unit. + + + + - Show which units are started after or before - with list-dependencies, respectively. - + With list-dependencies, show the + units that are ordered after the specified unit. In other + words, list the units that are in the Before= + directive of the specified unit, have the specified unit in + their After= directive, or otherwise depend + on the specified unit. @@ -174,10 +186,11 @@ along with systemd; If not, see . - Do not ellipsize unit names, process tree entries, and - truncate unit descriptions in the output of - list-units and - list-jobs. + Do not ellipsize unit names, process tree entries, + journal output, or truncate unit descriptions in the output + of status, list-units, + list-jobs, and + list-timers. @@ -193,8 +206,8 @@ along with systemd; If not, see . - When queuing a new job, control how to deal with already - queued jobs. Takes one of fail, + When queuing a new job, this option controls how to deal with + already queued jobs. It takes one of fail, replace, replace-irreversibly, isolate, @@ -217,8 +230,10 @@ along with systemd; If not, see . If replace-irreversibly is specified, operate like replace, but also mark the new jobs as irreversible. This prevents future conflicting - transactions from replacing these jobs. The jobs can still be - cancelled using the cancel command. + transactions from replacing these jobs (or even being enqueued + while the irreversible jobs are still pending). Irreversible + jobs can still be cancelled using the cancel + command. isolate is only valid for start operations and causes all other units to be stopped when the @@ -237,7 +252,7 @@ along with systemd; If not, see . applications. ignore-requirements is similar to - ignore-dependencies but only causes the + ignore-dependencies, but only causes the requirement dependencies to be ignored, the ordering dependencies will still be honoured. @@ -256,7 +271,7 @@ along with systemd; If not, see . sleep state. Any user may take these locks and privileged users may override these locks. If any locks are taken, shutdown and sleep state requests will normally fail - (regardless if privileged or not) and a list of active locks + (regardless of whether privileged or not) and a list of active locks is printed. However, if is specified, the locks are ignored and not printed, and the operation attempted anyway, possibly requiring additional @@ -273,6 +288,8 @@ along with systemd; If not, see . snapshot, is-active, is-failed, + is-enabled, + is-system-running, enable and disable. @@ -294,35 +311,13 @@ along with systemd; If not, see . - Do not print a legend, i.e. the column headers and + Do not print the legend, i.e. the column headers and the footer with hints. - - - - - Do not pipe output into a pager. - - - - - - - - Talk to the systemd system manager. (Default) - - - - - - - - Talk to the systemd manager of the calling - user. - - + + @@ -380,11 +375,36 @@ along with systemd; If not, see . When used with kill, choose which - processes to kill. Must be one of , - or to select - whether to kill only the main process of the unit, the - control process or all processes of the unit. If omitted, - defaults to . + processes to send a signal to. Must be one of + , or + to select whether to kill only the main + process, the control process or all processes of the + unit. The main process of the unit is the one that defines + the life-time of it. A control process of a unit is one that + is invoked by the manager to induce state changes of it. For + example, all processes started due to the + ExecStartPre=, + ExecStop= or + ExecReload= settings of service units are + control processes. Note that there is only one control + process per unit at a time, as only one state change is + executed at a time. For services of type + Type=forking, the initial process started + by the manager for ExecStart= is a + control process, while the process ultimately forked off by + that one is then considered the main process of the unit (if + it can be determined). This is different for service units + of other types, where the process forked off by the manager + for ExecStart= is always the main process + itself. A service unit consists of zero or one main process, + zero or one control process plus any number of additional + processes. Not all unit types manage processes of these + types however. For example, for mount units, control processes + are defined (which are the invocations of + /usr/bin/mount and + /usr/bin/umount), but no main process + is defined. If omitted, defaults to + . @@ -419,7 +439,7 @@ along with systemd; If not, see . safe option to request an immediate reboot. If is specified twice for these operations, they will be executed immediately without - terminating any processes or umounting any file + terminating any processes or unmounting any file systems. Warning: specifying twice with any of these operations might result in data loss. @@ -443,7 +463,7 @@ along with systemd; If not, see . When used with enable, - disable, is-enabled + disable, (and related commands), make changes only temporarily, so that they are lost on the next reboot. This will have the effect that changes are not made in subdirectories of @@ -451,7 +471,7 @@ along with systemd; If not, see . with identical immediate effects, however, since the latter is lost on reboot, the changes are lost too. - Similar, when used with + Similarly, when used with set-property, make changes only temporarily, so that they are lost on the next reboot. @@ -459,26 +479,19 @@ along with systemd; If not, see . - - + - Execute the operation remotely. Specify a hostname, or - username and hostname separated by @, to - connect to. This will use SSH to talk to the remote systemd - instance. + Takes one of full (the default), + enable-only, + disable-only. When use with the + preset or preset-all + commands controls whether units shall be disabled and + enabled according to the preset rules, or only enabled, or + only disabled. - - - - - Execute the operation on a local - container. Specify a container name to connect - to. - - @@ -513,6 +526,12 @@ along with systemd; If not, see . + + + + + + @@ -526,22 +545,26 @@ along with systemd; If not, see . - list-units + list-units PATTERN... List known units (subject to limitations specified - with ). + with ). If one or more + PATTERNs are specified, only + units matching one of them are shown. This is the default command. - list-sockets + list-sockets PATTERN... - List socket units ordered by the listening address. Produces output - similar to + List socket units ordered by listening address. + If one or more PATTERNs are + specified, only socket units matching one of them are + shown. Produces output similar to LISTEN UNIT ACTIVATES /dev/initctl systemd-initctl.socket systemd-initctl.service @@ -549,8 +572,7 @@ LISTEN UNIT ACTIVATES [::]:22 sshd.socket sshd.service kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service -5 sockets listed. - +5 sockets listed. Note: because the addresses might contains spaces, this output is not suitable for programmatic consumption. @@ -561,10 +583,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - list-timers + list-timers PATTERN... - List timer units ordered by the time they elapse next. + List timer units ordered by the time they elapse + next. If one or more PATTERNs + are specified, only units matching one of them are shown. + See also the options and . @@ -572,15 +597,24 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - start NAME... + start PATTERN... Start (activate) one or more units specified on the command line. + + Note that glob patterns operate on a list of currently + loaded units. Units which are not active and are not in a + failed state usually are not loaded, and would not be + matched by any pattern. In addition, in case of + instantiated units, systemd is often unaware of the + instance name until the instance has been started. Therefore, + using glob patterns with start + has limited usefulness. - stop NAME... + stop PATTERN... Stop (deactivate) one or more units specified on the @@ -588,7 +622,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reload NAME... + reload PATTERN... Asks all units listed on the command line to reload @@ -609,7 +643,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - restart NAME... + restart PATTERN... Restart one or more units specified on the command @@ -618,7 +652,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - try-restart NAME... + try-restart PATTERN... Restart one or more units specified on the command @@ -629,7 +663,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reload-or-restart NAME... + reload-or-restart PATTERN... Reload one or more units if they support it. If not, @@ -638,7 +672,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reload-or-try-restart NAME... + reload-or-try-restart PATTERN... Reload one or more units if they support it. If not, @@ -668,56 +702,68 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - kill NAME... + kill PATTERN... Send a signal to one or more processes of the unit. Use to select which - process to kill. Use to select - the kill mode and to select the - signal to send. + process to kill. Use to select + the signal to send. - is-active NAME... + is-active PATTERN... Check whether any of the specified units are active - (i.e. running). Returns an exit code 0 if at least one is - active, non-zero otherwise. Unless - is specified, this will also print the current unit state to - STDOUT. + (i.e. running). Returns an exit code + 0 if at least one is active, or + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. - is-failed NAME... + is-failed PATTERN... - Check whether any of the specified units are in a "failed" state. - Returns an exit code 0 if at least one has failed, non-zero - otherwise. Unless is specified, this - will also print the current unit state to - STDOUT. + Check whether any of the specified units are in a + "failed" state. Returns an exit code + 0 if at least one has failed, + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. - status [NAME...|PID...] + status PATTERN...|PID...] Show terse runtime status information about one or more units, followed by most recent log data from the - journal. If no units are specified, show all units (subject - to limitations specified with ). If a PID - is passed, show information about the unit the process - belongs to. + journal. If no units are specified, show system status. If + combined with , also show the status of + all units (subject to limitations specified with + ). If a PID is passed, show information + about the unit the process belongs to. This function is intended to generate human-readable - output. If you are looking for computer-parsable output, use - show instead. + output. If you are looking for computer-parsable output, + use show instead. By default this + function only shows 10 lines of output and ellipsizes + lines to fit in the terminal window. This can be changes + with and , + see above. In addition, journalctl + --unit=NAME or + journalctl + --user-unit=NAME use + a similar filter for messages and might be more + convenient. + - show [NAME...|JOB...] + show PATTERN...|JOB... Show properties of one or more units, jobs, or the @@ -734,13 +780,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - cat NAME... + cat PATTERN... - Show backing files of one or more units. - Prints the fragment, drop-ins, and source (sysvinit compat) - of units. Each file is preceded by a comment which includes the - file name. + Show backing files of one or more units. Prints the + "fragment" and "drop-ins" (source files) of units. Each + file is preceded by a comment which includes the file + name. @@ -770,7 +816,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - help NAME...|PID... + help PATTERN...|PID... Show manual pages for one or more units, if @@ -780,7 +826,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reset-failed [NAME...] + reset-failed [PATTERN...] Reset the failed state of the @@ -814,10 +860,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - list-unit-files + list-unit-files PATTERN... - List installed unit files. + List installed unit files. If one or more + PATTERNs are specified, only + units whose filename (just the last component of the path) + matches one of them are shown. @@ -910,10 +959,64 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service Checks whether any of the specified unit files are - enabled (as with enable). Returns an exit - code of 0 if at least one is enabled, non-zero - otherwise. Prints the current enable status. To suppress - this output, use . + enabled (as with enable). Returns an + exit code of 0 if at least one is enabled, non-zero + otherwise. Prints the current enable status (see table). + To suppress this output, use . + + + + + <command>is-enabled</command> output + + + + + + Printed string + Meaning + Return value + + + + + enabled + Enabled through a symlink in .wants directory (permanently or just in /run) + 0 + + + enabled-runtime + + + linked + Made available through a symlink to the unit file (permanently or just in /run) + 1 + + + linked-runtime + + + masked + Disabled entirely (permanently or just in /run) + 1 + + + masked-runtime + + + static + Unit is not enabled, but has no provisions for enabling in [Install] section + 0 + + + disabled + Unit is not enabled + 1 + + + +
+ @@ -938,16 +1041,35 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service command line, to the defaults configured in the preset policy files. This has the same effect as disable or enable, - depending how the unit is listed in the preset files. For - more information on the preset policy format, see + depending how the unit is listed in the preset files. + + Use to control + whether units shall be enabled and disabled, or only + enabled, or only disabled. + + For more information on the preset policy format, + see systemd.preset5. For more information on the concept of presets, please - consult the - Preset + consult the Preset document. + + preset-all + + + Resets all installed unit files to the defaults + configured in the preset policy file (see above). + + Use to control + whether units shall be enabled and disabled, or only + enabled, or only disabled. + + + mask NAME... @@ -960,7 +1082,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service activation of the unit, including manual activation. Use this option with care. This honors the option to only mask temporarily - until the next reoobt of the system. + until the next reboot of the system. @@ -1008,15 +1130,35 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + + Machine Commands + + + + list-machines PATTERN... + + + List the host and all running local containers with + their state. If one or more + PATTERNs are specified, only + containers matching one of them are shown. + + + + + + Job Commands - list-jobs + list-jobs PATTERN... - List jobs that are in progress. + List jobs that are in progress. If one or more + PATTERNs are specified, only + jobs for units matching one of them are shown. @@ -1036,14 +1178,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - snapshot [NAME] + snapshot NAME Create a snapshot. If a snapshot name is specified, the new snapshot will be named after it. If none is - specified, an automatic snapshot name is generated. In either - case, the snapshot name used is printed to STDOUT, unless - is specified. + specified, an automatic snapshot name is generated. In + either case, the snapshot name used is printed to standard + output, unless is specified. + A snapshot refers to a saved state of the systemd manager. It is implemented itself as a unit that is @@ -1060,7 +1203,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - delete NAME... + delete PATTERN... Remove a snapshot previously created with @@ -1104,6 +1247,19 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service specified value. + + import-environment VARIABLE... + + + Import all, one or more environment variables set on + the client into the systemd manager environment block. If + no arguments are passed, the entire environment block is + imported. Otherwise, a list of one or more environment + variable names should be passed, whose client-side values + are then imported into the manager's environment + block. + + @@ -1145,6 +1301,20 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service System Commands + + is-system-running + + + Checks whether the system is running. This returns + success when the system is fully up and running, meaning + not in startup, shutdown or maintainance mode. Failure is + returned otherwise. In addition, the current state is + printed in a short string to standard output. Use + to suppress output of this state + string. + + + default @@ -1153,6 +1323,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service isolate default.target. + rescue @@ -1281,7 +1452,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - switch-root ROOT [INIT] + switch-root ROOT INIT Switches to a different root directory and executes a @@ -1306,23 +1477,55 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service Parameter Syntax - For unit commands the specified - NAME should be the full name of the - unit, or an abbreviated name which is automatically extended with - the .service suffix. - # systemctl start foo.service is equivalent to: - # systemctl start foo - Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) paths to mount unit names. - # systemctl status /dev/sda -# systemctl status /home is equivalent to: - # systemctl status dev-sda.device -# systemctl status home.mount - - For unit file commands the - specified NAME should be the full name - of the unit file, or the absolute path to the unit file. - # systemctl link /path/to/foo.service - + Unit commands listed above take either a single unit name + (designated as NAME), or multiple + unit specifications (designated as + PATTERN...). In the first case, the + unit name with or without a suffix must be given. If the suffix + is not specified, systemctl will append a suitable suffix, + .service by default, and a type-specific + suffix in case of commands which operate only on specific unit + types. For example, + # systemctl start sshd and + # systemctl start sshd.service + are equivalent, as are + # systemctl isolate snapshot-11 + and + # systemctl isolate snapshot-11.snapshot + Note that (absolute) paths to device nodes are automatically + converted to device unit names, and other (absolute) paths to + mount unit names. + # systemctl status /dev/sda +# systemctl status /home + are equivalent to: + # systemctl status dev-sda.device +# systemctl status home.mount + In the second case, shell-style globs will be matched against + currently loaded units; literal unit names, with or without + a suffix, will be treated as in the first case. This means that + literal unit names always refer to exactly one unit, but globs + may match zero units and this is not considered an error. + + Glob patterns use + fnmatch3, + so normal shell-style globbing rules are used, and + *, ?, + [] may be used. See + glob7 + for more details. The patterns are matched against the names of + currently loaded units, and patterns which do not match anything + are silently skipped. For example: + # systemctl stop sshd@*.service + will stop all sshd@.service instances. + + + For unit file commands, the specified + NAME should be the full name of the + unit file, or the absolute path to the unit file: + # systemctl enable foo.service + or + # systemctl link /path/to/foo.service + @@ -1334,23 +1537,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service code otherwise. - - Environment - - - - $SYSTEMD_PAGER - - - Pager to use when is not - given; overrides $PAGER. Setting this to - an empty string or the value cat is - equivalent to passing - . - - - - + See Also @@ -1364,6 +1551,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service systemd.special7, wall1, systemd.preset5 + glob7