X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=3ac6f628e2c516ed45719418243dd9f7128f0506;hp=58b2c2ad966b86ec24226fcaa1199fb154e945db;hb=92ff080be100aff15f292e2631921131c610afe7;hpb=4dc5b821ae737914499119e29811fc3346e3d97c diff --git a/man/systemctl.xml b/man/systemctl.xml index 58b2c2ad9..3ac6f628e 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1,4 +1,4 @@ - + @@ -21,7 +21,8 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> - + systemctl @@ -59,23 +60,12 @@ along with systemd; If not, see . Description - systemctl may be used to - introspect and control the state of the + systemctl may be used to introspect and + control the state of the systemd system and + service manager. Please refer to systemd1 - system and service manager. - - For unit commands, the NAME represents full name of the unit. - -systemctl start foo.service - - For unit file commands, the NAME represents the full name of the unit file, or the absolute path to the unit file. - -systemctl start /path/to/foo.service - - While working with services/service files, systemctl implicitly appends the ".service" suffix when it is missing. - -systemctl start foo - + for an introduction into the basic concepts and functionality this + tool manages. @@ -84,22 +74,6 @@ systemctl start foo The following options are understood: - - - - - Prints a short help - text and exits. - - - - - - - Prints a short version string and exits. - - - @@ -124,9 +98,10 @@ systemctl start foo - The argument should be a comma-separated list of unit LOAD, - SUB, or ACTIVE states. When listing units, show only those - in specified states. + The argument should be a comma-separated list of unit + LOAD, SUB, or ACTIVE states. When listing units, show only + those in specified states. Use + to show only failed units. @@ -159,26 +134,64 @@ systemctl start foo + + + + + + 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 + (:). + + + Show reverse dependencies between units with - list-dependencies, i.e. units with - dependencies of type Wants= or - Requires= on the given unit. + list-dependencies, i.e. follow + dependencies of type WantedBy=, + RequiredBy=, + RequiredByOverrridable=, + PartOf=, BoundBy=, + instead of Wants= and similar. + + + With list-dependencies, show the + units that are ordered before the specified unit. In other + words, recursively list units following the + After= dependency. + + Note that any After= dependency is + automatically mirrored to create a + Before= dependency. Temporal dependencies + may be specified explicitly, but are also created implicitly + for units which are WantedBy= targets + (see + systemd.target5), + and as a result of other directives (for example + RequiresMountsFor=). Both explicitly + and implicitly introduced dependencies are shown with + list-dependencies. + + + + - 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, recursively list units following the + Before= dependency. @@ -187,10 +200,11 @@ systemctl start foo - 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. @@ -206,8 +220,8 @@ systemctl start foo - 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, @@ -230,8 +244,10 @@ systemctl start foo 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 @@ -250,7 +266,7 @@ systemctl start foo 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. @@ -269,7 +285,7 @@ systemctl start foo 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 @@ -286,6 +302,8 @@ systemctl start foo snapshot, is-active, is-failed, + is-enabled, + is-system-running, enable and disable. @@ -307,35 +325,18 @@ systemctl start foo - 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. - - + @@ -393,11 +394,36 @@ systemctl start foo 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 + . @@ -432,7 +458,7 @@ systemctl start foo 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. @@ -456,7 +482,7 @@ systemctl start foo When used with enable, - disable, is-enabled + disable, edit, (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 @@ -464,7 +490,7 @@ systemctl start foo 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. @@ -472,26 +498,19 @@ systemctl start foo - - + - 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 used 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. - - @@ -526,6 +545,12 @@ systemctl start foo + + + + + + @@ -539,22 +564,26 @@ systemctl start foo - 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 @@ -562,38 +591,49 @@ 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. See also the options , - , and . + , and . - 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 - . + . - 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 @@ -601,7 +641,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 @@ -616,13 +656,12 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service file. This command should not be confused with the - daemon-reload or load - commands. + daemon-reload command. - restart NAME... + restart PATTERN... Restart one or more units specified on the command @@ -631,7 +670,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 @@ -642,7 +681,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, @@ -651,7 +690,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, @@ -666,7 +705,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service Start the unit specified on the command line and its - dependencies and stop all others. + dependencies and stop all others. If a unit name with no + extension is given, an extension of + .target will be assumed. This is similar to changing the runlevel in a traditional init system. The isolate @@ -681,56 +722,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 @@ -746,7 +799,16 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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... @@ -774,7 +836,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 @@ -784,7 +846,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - reset-failed [NAME...] + reset-failed [PATTERN...] Reset the failed state of the @@ -799,15 +861,30 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - list-dependencies NAME + + list-dependencies + NAME + - Shows required and wanted units of the specified - unit. If no unit is specified, - default.target is implied. Target units - are recursively expanded. When is - passed, all other units are recursively expanded as - well. + Shows units required and wanted by the specified + unit. This recursively lists units following the + Requires=, + RequiresOverridable=, + Requisite=, + RequisiteOverridable=, + Wants=, BindsTo= + dependencies. If no unit is specified, + default.target is implied. + + By default, only target units are recursively + expanded. When is passed, all other + units are recursively expanded as well. + + Options , + , + may be used to change what types of dependencies + are shown. @@ -818,10 +895,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. @@ -878,6 +958,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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. + + Using enable on masked units + results in an error. @@ -914,10 +997,69 @@ 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 file is not enabled, and has no provisions for enabling in the [Install] section. + 0 + + + indirect + Unit file itself is not enabled, but it has a non-empty Also= setting in the [Install] section, listing other unit files that might be enabled. + 0 + + + disabled + Unit file is not enabled. + 1 + + + +
+ @@ -942,16 +1084,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... @@ -961,10 +1122,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service /dev/null, making it impossible to 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 honors the + activation of the unit, including enablement and 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. @@ -978,6 +1139,25 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + + add-wants TARGET + NAME... + add-requires TARGET + NAME... + + + Adds Wants= resp. Requires= + dependency to the specified TARGET for + one or more units. + + This command honors , + , and + in a similar way as + enable. + + + + link FILENAME... @@ -1009,6 +1189,61 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service default.target to the given unit. + + + edit NAME... + + + Edit a drop-in snippet or a whole replacement file if + is specified, to extend or override the + specified unit. + + Depending on whether (the default), + , or is specified, + this creates a drop-in file for each unit either for the system, + for the calling user or for all futures logins of all users. Then, + the editor (see the "Environment" section below) is invoked on + temporary files which will be written to the real location if the + editor exits successfully. + + If is specified, this will copy the + original units instead of creating drop-in files. + + If is specified, the changes will + be made temporarily in /run and they will be + lost on the next reboot. + + If the temporary file is empty upon exit the modification of + the related unit is canceled + + After the units have been edited, systemd configuration is + reloaded (in a way that is equivalent to daemon-reload). + + + Note that this command cannot be used to remotely edit units + and that you cannot temporarily edit units which are in + /etc since they take precedence over + /run. + + + + + + + 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. + + + @@ -1017,10 +1252,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. @@ -1040,14 +1277,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 @@ -1064,7 +1302,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - delete NAME... + delete PATTERN... Remove a snapshot previously created with @@ -1108,6 +1346,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. + + @@ -1122,10 +1373,9 @@ 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 being reloaded, all sockets systemd - listens on on behalf of user configuration will stay + listens on behalf of user configuration will stay accessible. This command should not be confused - with the load or - reload commands. + with the reload command. @@ -1149,6 +1399,69 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service System Commands + + is-system-running + + + Checks whether the system is operational. This + returns success when the system is fully up and running, + meaning not in startup, shutdown or maintenance + mode. Failure is returned otherwise. In addition, the + current state is printed in a short string to standard + output, see table below. Use to + suppress this output. + + + Manager Operational States + + + + + + Name + Description + + + + + initializing + Early bootup, before + basic.target is reached + or the maintenance state entered. + + + + starting + Late bootup, before the job queue + becomes idle for the first time, or one of the + rescue targets are reached. + + + running + The system is fully + operational. + + + degraded + The system is operational but one or more + units failed. + + + maintenance + The rescue or emergency target is + active. + + + stopping + The manager is shutting + down. + + + +
+ + + default @@ -1157,6 +1470,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service isolate default.target. + rescue @@ -1285,7 +1599,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 @@ -1307,6 +1621,60 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + + Parameter Syntax + + 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 default + and + # systemctl isolate default.target + 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 + + + @@ -1321,17 +1689,22 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - $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 - . - + $SYSTEMD_EDITOR + + Editor to use when editing units; overrides + $EDITOR and $VISUAL. If neither + $SYSTEMD_EDITOR nor $EDITOR nor + $VISUAL are present or if it is set to an empty + string or if their execution failed, systemctl will try to execute well + known editors in this order: + nano1, + vim1, + vi1. + + + @@ -1344,8 +1717,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service systemd.unit5, systemd.resource-management5, systemd.special7, - wall1, - systemd.preset5 + wall1, + systemd.preset5, + glob7