X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=13a4444a0437e16aecd274d2282a65c1cd59ea0e;hp=1642a47273c0958b5e3411a7104ad4c5054139ed;hb=e3e0314b56012f7febc279d268f2cadc1fcc0f25;hpb=27722f964361a7da2532cf0a2d57a2f0dd0a09f2 diff --git a/man/systemctl.xml b/man/systemctl.xml index 1642a4727..13a4444a0 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -174,22 +174,11 @@ along with systemd; If not, see . - Do not ellipsize unit names, cgroup members, and - truncate unit descriptions in the output of - list-units and - list-jobs. - - - - - - - - If the requested operation conflicts with a pending - unfinished job, fail the command. If this is not specified, - the requested operation will replace the pending job, if - necessary. Do not confuse with - . + 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. @@ -202,27 +191,58 @@ along with systemd; If not, see . - + - Mark this transaction's jobs as irreversible. This prevents - future conflicting transactions from replacing these jobs. - The jobs can still be cancelled using the cancel - command. + When queuing a new job, this option controls how to deal with + already queued jobs. It takes one of fail, + replace, + replace-irreversibly, + isolate, + ignore-dependencies, + ignore-requirements or + flush. Defaults to + replace, except when the + isolate command is used which implies the + isolate job mode. + + If fail is specified and a requested + operation conflicts with a pending job (more specifically: + causes an already pending start job to be reversed into a stop + job or vice versa), cause the operation to fail. + + If replace (the default) is + specified, any conflicting pending job will be replaced, as + necessary. + + 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. + + isolate is only valid for start + operations and causes all other units to be stopped when the + specified unit is started. This mode is always used when the + isolate command is used. + + flush will cause all queued jobs to + be canceled when the new job is enqueued. + + If ignore-dependencies is specified, + then all unit dependencies are ignored for this new job and + the operation is executed immediately. If passed, no required + units of the unit passed will be pulled in, and no ordering + dependencies will be honored. This is mostly a debugging and + rescue tool for the administrator and should not be used by + applications. + + ignore-requirements is similar to + ignore-dependencies, but only causes the + requirement dependencies to be ignored, the ordering + dependencies will still be honoured. - - - - - - When enqueuing a new job, ignore all its dependencies - and execute it immediately. If passed, no required units of - the unit passed will be pulled in, and no ordering - dependencies will be honored. This is mostly a debugging and - rescue tool for the administrator and should not be used by - applications. - @@ -237,7 +257,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 @@ -275,7 +295,7 @@ 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. @@ -424,7 +444,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 @@ -432,7 +452,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. @@ -444,21 +464,20 @@ along with systemd; If not, see . - Execute operation remotely. Specify a hostname, or - username and hostname separated by @, to connect to. This - will use SSH to talk to the remote systemd + 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. - - + + - - Acquire privileges via PolicyKit before executing the - operation. - + Execute the operation on a local + container. Specify a container name to connect + to. @@ -508,22 +527,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 @@ -543,15 +566,38 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - start NAME... + list-timers PATTERN... + + + 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 + . + + + + + 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 @@ -559,14 +605,14 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reload NAME... + reload PATTERN... Asks all units listed on the command line to reload their configuration. Note that this will reload the service-specific configuration, not the unit configuration file of systemd. If you want systemd to reload the - configuration file of a unit use the + configuration file of a unit, use the daemon-reload command. In other words: for the example case of Apache, this will reload Apache's httpd.conf in the web server, not the @@ -580,7 +626,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - restart NAME... + restart PATTERN... Restart one or more units specified on the command @@ -589,7 +635,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 @@ -600,7 +646,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, @@ -609,7 +655,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, @@ -639,7 +685,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - kill NAME... + kill PATTERN... Send a signal to one or more processes of the @@ -650,18 +696,18 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - 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 + active, or non-zero otherwise. Unless is specified, this will also print the current unit state to STDOUT. - is-failed NAME... + is-failed PATTERN... Check whether any of the specified units are in a "failed" state. @@ -672,7 +718,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - status [NAME...|PID...] + status PATTERN...|PID...] Show terse runtime status information about one or @@ -683,42 +729,61 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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 - manager itself. If no argument is specified properties of - the manager will be shown. If a unit name is specified + manager itself. If no argument is specified, properties of + the manager will be shown. If a unit name is specified, properties of the unit is shown, and if a job id is - specified properties of the job is shown. By default, empty + specified, properties of the job is shown. By default, empty properties are suppressed. Use to - show those too. To select specific properties to show use + show those too. To select specific properties to show, use . This command is intended to be used whenever computer-parsable output is required. Use status if you are looking for formatted human-readable output. + + cat PATTERN... + + 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. + + set-property NAME ASSIGNMENT... Set the specified unit properties at runtime where this is supported. This allows changing configuration - parameter properties such as resource management controls at + parameter properties such as resource control settings at runtime. Not all properties may be changed at runtime, but - many resource management settings (primarily those in - systemd.cgroup5) + many resource control settings (primarily those in + systemd.resource-control5) may. The changes are applied instantly, and stored on disk for future boots, unless is - passed, in which case the settings only apply until the next - reboot. The syntax of the property assignment follows + passed, in which case the settings only apply until the + next reboot. The syntax of the property assignment follows closely the syntax of assignments in unit files. Example: systemctl set-property foobar.service CPUShares=777 @@ -732,7 +797,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 @@ -742,7 +807,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reset-failed [NAME...] + reset-failed [PATTERN...] Reset the failed state of the @@ -776,10 +841,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. @@ -830,10 +898,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service case of socket units), and so on. Depending on whether , - or is - specified, this enables the unit for the system, for the - calling user only or for all future logins of all - users. Note that in the last case, no systemd daemon + , , + or is specified, this enables the unit + for the system, for the calling user only, for only this boot of + the system, or for all future logins of all users, or only this + boot. Note that in the last case, no systemd daemon configuration is reloaded. @@ -860,8 +929,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service This command honors , - , in a - similar way as enable. + , and + in a similar way as + enable. @@ -870,10 +940,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 + + + +
+ @@ -918,7 +1042,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service start them. This is a stronger version of disable, since it prohibits all kinds of activation of the unit, including manual activation. Use - this option with care. + this option with care. This honors the + option to only mask temporarily + until the next reoobt of the system. @@ -971,10 +1097,12 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - 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. @@ -994,7 +1122,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - snapshot [NAME] + snapshot NAME Create a snapshot. If a snapshot name is specified, @@ -1018,7 +1146,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - delete NAME... + delete PATTERN... Remove a snapshot previously created with @@ -1075,7 +1203,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service Reload systemd manager configuration. This will reload all unit files and recreate the entire dependency - tree. While the daemon is reloaded, all sockets systemd + tree. While the daemon is being reloaded, all sockets systemd listens on on behalf of user configuration will stay accessible. This command should not be confused with the load or @@ -1089,9 +1217,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service Reexecute the systemd manager. This will serialize the manager state, reexecute the process and deserialize the state again. This command is of little use except for - debugging and package upgrades. Sometimes it might be + debugging and package upgrades. Sometimes, it might be helpful as a heavy-weight daemon-reload. - While the daemon is reexecuted, all sockets systemd listening + While the daemon is being reexecuted, all sockets systemd listening on behalf of user configuration will stay accessible. @@ -1162,7 +1290,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reboot + reboot arg Shut down and reboot the system. This is mostly @@ -1175,6 +1303,16 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service specified twice, the operation is immediately executed without terminating any processes or unmounting any file systems. This may result in data loss. + + If the optional argument + arg is given, it will be passed + as the optional argument to the + reboot2 + system call. The value is architecture and firmware + specific. As an example, recovery might + be used to trigger system recovery, and + fota might be used to trigger a + firmware over the air update. @@ -1229,7 +1367,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 @@ -1251,6 +1389,60 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + + Parameter Syntax + + Unit ommands 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, and 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 don't 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 + + + @@ -1286,10 +1478,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service journalctl1, loginctl1, systemd.unit5, - systemd.cgroup5, + systemd.resource-management5, systemd.special7, wall1, systemd.preset5 + glob7