diff options
Diffstat (limited to 'upstream/debian-unstable/man1/systemctl.1')
| -rw-r--r-- | upstream/debian-unstable/man1/systemctl.1 | 289 |
1 files changed, 246 insertions, 43 deletions
diff --git a/upstream/debian-unstable/man1/systemctl.1 b/upstream/debian-unstable/man1/systemctl.1 index e6609537..9de3380d 100644 --- a/upstream/debian-unstable/man1/systemctl.1 +++ b/upstream/debian-unstable/man1/systemctl.1 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMCTL" "1" "" "systemd 255" "systemctl" +.TH "SYSTEMCTL" "1" "" "systemd 256~rc3" "systemctl" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -394,7 +394,7 @@ For details about many of these properties, see the documentation of the D\-Bus .PP \fBcat \fR\fB\fIPATTERN\fR\fR\fB\&...\fR .RS 4 -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\&. Note that this shows the contents of the backing files on disk, which may not match the system manager\*(Aqs understanding of these units if any unit files were updated on disk and the +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\&. Note that this shows the contents of the backing files on disk, which might not match the system manager\*(Aqs understanding of these units if any unit files were updated on disk and the \fBdaemon\-reload\fR command wasn\*(Aqt issued since\&. .sp @@ -574,6 +574,64 @@ is selected, see \fB\-\-what=\fR is not specified, the cache and runtime data as well as the file descriptor store are removed (as these three types of resources are generally redundant and reproducible on the next invocation of the unit)\&. Note that the specified units must be stopped to invoke this operation\&. .sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \& Possible values for \-\-what= +.TS +allbox tab(:); +lB lB. +T{ +Value +T}:T{ +Unit Setting +T} +.T& +l l +l l +l l +l l +l l +l l +l l. +T{ +"runtime" +T}:T{ +\fIRuntimeDirectory=\fR +T} +T{ +"state" +T}:T{ +\fIStateDirectory=\fR +T} +T{ +"cache" +T}:T{ +\fICacheDirectory=\fR +T} +T{ +"logs" +T}:T{ +\fILogsDirectory=\fR +T} +T{ +"configuration" +T}:T{ +\fIConfigurationDirectory=\fR +T} +T{ +"fdstore" +T}:T{ +\fIFileDescriptorStorePreserve=\fR +T} +T{ +"all" +T}:T{ +All of the above +T} +.TE +.sp 1 Added in version 243\&. .RE .PP @@ -967,7 +1025,7 @@ Checks whether any of the specified unit files are enabled (as with .nr an-no-space-flag 1 .nr an-break-flag 1 .br -.B Table\ \&1.\ \& is\-enabled output +.B Table\ \&2.\ \& is\-enabled output .TS allbox tab(:); lB lB lB. @@ -1186,29 +1244,34 @@ Added in version 217\&. .PP \fBedit \fR\fB\fIUNIT\fR\fR\fB\&...\fR .RS 4 -Edit a drop\-in snippet or a whole replacement file if -\fB\-\-full\fR -is specified, to extend or override the specified unit\&. +Edit or replace a drop\-in snippet or the main unit file, to extend or override the definition of the specified unit\&. .sp Depending on whether \fB\-\-system\fR (the default), \fB\-\-user\fR, or \fB\-\-global\fR -is specified, this command 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\&. +is specified, this command will operate on the system unit files, unit files for the calling user, or the unit files shared between all users\&. .sp -If -\fB\-\-drop\-in=\fR -is specified, the given drop\-in file name will be used instead of the default -override\&.conf\&. +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\&. After the editing is finished, configuration is reloaded, equivalent to +\fBsystemctl daemon\-reload \-\-system\fR +or +\fBsystemctl daemon\-reload \-\-user\fR\&. For +\fBedit \-\-global\fR, the reload is not performed and the edits will take effect only for subsequent logins (or after a reload is requested in a different way)\&. .sp If \fB\-\-full\fR -is specified, this will copy the original units instead of creating drop\-in files\&. +is specified, a replacement for the main unit file will be created or edited\&. Otherwise, a drop\-in file will be created or edited\&. .sp If +\fB\-\-drop\-in=\fR +is specified, the given drop\-in file name will be used instead of the default +override\&.conf\&. +.sp +The unit must exist, i\&.e\&. its main unit file must be present\&. If \fB\-\-force\fR -is specified and any units do not already exist, new unit files will be opened for editing\&. +is specified, this requirement is ignored and a new unit may be created (with +\fB\-\-full\fR), or a drop\-in for a nonexistent unit may be created\&. .sp If \fB\-\-runtime\fR @@ -1216,10 +1279,11 @@ is specified, the changes will be made temporarily in /run/ and they will be lost on the next reboot\&. .sp -If the temporary file is empty upon exit, the modification of the related unit is canceled\&. +If +\fB\-\-stdin\fR +is specified, the new contents will be read from standard input\&. In this mode, the old contents of the file are discarded\&. .sp -After the units have been edited, systemd configuration is reloaded (in a way that is equivalent to -\fBdaemon\-reload\fR)\&. +If the temporary file is empty upon exit, the modification of the related unit is canceled\&. .sp 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 @@ -1299,11 +1363,21 @@ Dump the systemd manager environment block\&. This is the environment block that \fBdash\fR(1) or \fBfish\fR(1)\&. +.sp +Note that this shows the +\fIeffective\fR +block, i\&.e\&. the combination of environment variables configured via configuration files, environment generators and via IPC (i\&.e\&. via the +\fBset\-environment\fR +described below)\&. At the moment a unit process is forked off this combined environment block will be further combined with per\-unit environment variables, which are not visible in this command\&. .RE .PP \fBset\-environment \fR\fB\fIVARIABLE=VALUE\fR\fR\fB\&...\fR .RS 4 -Set one or more systemd manager environment variables, as specified on the command line\&. This command will fail if variable names and values do not conform to the rules listed above\&. +Set one or more service manager environment variables, as specified on the command line\&. This command will fail if variable names and values do not conform to the rules listed above\&. +.sp +Note that this operates on an environment block separate from the environment block configured from service manager configuration and environment generators\&. Whenever a process is invoked the two blocks are combined (also incorporating any per\-service environment variables), and passed to it\&. The +\fBshow\-environment\fR +verb will show the combination of the blocks, see above\&. .sp Added in version 233\&. .RE @@ -1312,6 +1386,10 @@ Added in version 233\&. .RS 4 Unset one or more systemd manager environment variables\&. If only a variable name is specified, it will be removed regardless of its value\&. If a variable and a value are specified, the variable is only removed if it has the specified value\&. .sp +Note that this operates on an environment block separate from the environment block configured from service manager configuration and environment generators\&. Whenever a process is invoked the two blocks are combined (also incorporating any per\-service environment variables), and passed to it\&. The +\fBshow\-environment\fR +verb will show the combination of the blocks, see above\&. Note that this means this command cannot be used to unset environment variables defined in the service manager configuration files or via generators\&. +.sp Added in version 233\&. .RE .PP @@ -1405,7 +1483,7 @@ or .nr an-no-space-flag 1 .nr an-break-flag 1 .br -.B Table\ \&2.\ \&is\-system\-running output +.B Table\ \&3.\ \&is\-system\-running output .TS allbox tab(:); lB lB lB. @@ -1676,16 +1754,49 @@ Switches to a different root directory and executes a new system manager process Added in version 209\&. .RE .PP +\fBsleep\fR +.RS 4 +Put the system to sleep, through +\fBsuspend\fR, +\fBhibernate\fR, +\fBhybrid\-sleep\fR, or +\fBsuspend\-then\-hibernate\fR\&. The sleep operation to use is automatically selected by +\fBsystemd-logind.service\fR(8)\&. By default, +\fBsuspend\-then\-hibernate\fR +is used, and falls back to +\fBsuspend\fR +and then +\fBhibernate\fR +if not supported\&. Refer to +\fISleepOperation=\fR +setting in +\fBlogind.conf\fR(5) +for more details\&. This command is asynchronous, and will return after the sleep operation is successfully enqueued\&. It will not wait for the sleep/resume cycle to complete\&. +.sp +Added in version 256\&. +.RE +.PP \fBsuspend\fR .RS 4 Suspend the system\&. This will trigger activation of the special target unit suspend\&.target\&. This command is asynchronous, and will return after the suspend operation is successfully enqueued\&. It will not wait for the suspend/resume cycle to complete\&. +.sp +If +\fB\-\-force\fR +is specified, and +\fBsystemd\-logind\fR +returned error for the operation, the error will be ignored and the operation will be tried again directly through starting the target unit\&. .RE .PP \fBhibernate\fR .RS 4 Hibernate the system\&. This will trigger activation of the special target unit hibernate\&.target\&. This command is asynchronous, and will return after the hibernation operation is successfully enqueued\&. It will not wait for the hibernate/thaw cycle to complete\&. +.sp +This command honors +\fB\-\-force\fR +in the same way as +\fBsuspend\fR\&. .RE .PP \fBhybrid\-sleep\fR @@ -1693,15 +1804,26 @@ hibernate\&.target\&. This command is asynchronous, and will return after the hi Hibernate and suspend the system\&. This will trigger activation of the special target unit hybrid\-sleep\&.target\&. This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued\&. It will not wait for the sleep/wake\-up cycle to complete\&. .sp +This command honors +\fB\-\-force\fR +in the same way as +\fBsuspend\fR\&. +.sp Added in version 196\&. .RE .PP \fBsuspend\-then\-hibernate\fR .RS 4 -Suspend the system and hibernate it after the delay specified in -systemd\-sleep\&.conf\&. This will trigger activation of the special target unit +Suspend the system and hibernate it when the battery is low, or when the delay specified in +systemd\-sleep\&.conf +elapsed\&. This will trigger activation of the special target unit suspend\-then\-hibernate\&.target\&. This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued\&. It will not wait for the sleep/wake\-up or hibernate/thaw cycle to complete\&. .sp +This command honors +\fB\-\-force\fR +in the same way as +\fBsuspend\fR\&. +.sp Added in version 240\&. .RE .SS "Parameter Syntax" @@ -1799,7 +1921,7 @@ for more details\&. The patterns are matched against the primary names of units .RS 4 .\} .nf -# systemctl stop sshd@*\&.service +# systemctl stop "sshd@*\&.service" .fi .if n \{\ .RE @@ -2240,7 +2362,19 @@ on units that are enabled in global scope, when a \fBstop\fR\-ped, \fBdisable\fR\-d, or -\fBmask\fR\-ed unit still has active triggering units\&. +\fBmask\fR\-ed unit still has active triggering units, +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +when a unit file is changed and requires +\fBdaemon\-reload\fR\&. .RE .sp Added in version 253\&. @@ -2256,13 +2390,19 @@ will wait until the unit\*(Aqs start\-up is completed\&. By passing this argumen .PP \fB\-\-wait\fR .RS 4 -Synchronously wait for started units to terminate again\&. This option may not be combined with +When used with +\fBstart\fR +or +\fBrestart\fR, synchronously wait for started units to terminate again\&. This option may not be combined with \fB\-\-no\-block\fR\&. Note that this will wait forever if any given unit never terminates (by itself or by getting stopped explicitly); particularly services which use "RemainAfterExit=yes"\&. .sp When used with \fBis\-system\-running\fR, wait until the boot process is completed before returning\&. .sp +When used with +\fBkill\fR, wait until the signalled units terminate\&. Note that this will wait forever if any given unit never terminates\&. +.sp Added in version 232\&. .RE .PP @@ -2341,7 +2481,7 @@ and Added in version 252\&. .RE .PP -\fB\-\-kill\-value=\fR\fIINT\fR +\fB\-\-kill\-value=\fR\fB\fIINT\fR\fR .RS 4 If used with the \fBkill\fR @@ -2415,20 +2555,42 @@ When used with \fBedit\fR, create all of the specified units which do not already exist\&. .sp When used with +\fBsuspend\fR, +\fBhibernate\fR, +\fBhybrid\-sleep\fR, or +\fBsuspend\-then\-hibernate\fR, the error returned by +\fBsystemd\-logind\fR +will be ignored, and the operation will be performed directly through starting the corresponding units\&. +.sp +When used with \fBhalt\fR, \fBpoweroff\fR, -\fBreboot\fR -or +\fBreboot\fR, or \fBkexec\fR, execute the selected operation without shutting down all units\&. However, all processes will be killed forcibly and all file systems are unmounted or remounted read\-only\&. This is hence a drastic but relatively safe option to request an immediate reboot\&. If \fB\-\-force\fR is specified twice for these operations (with the exception of -\fBkexec\fR), they will be executed immediately, without terminating any processes or unmounting any file systems\&. Warning: specifying +\fBkexec\fR), they will be executed immediately, without terminating any processes or unmounting any file systems\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Specifying \fB\-\-force\fR twice with any of these operations might result in data loss\&. Note that when \fB\-\-force\fR is specified twice the selected operation is executed by \fBsystemctl\fR itself, and the system manager is not contacted\&. This means the command should succeed even when the system manager has crashed\&. +.sp .5v +.RE .RE .PP \fB\-\-message=\fR @@ -2663,7 +2825,7 @@ When used with Added in version 248\&. .RE .PP -\fB\-\-drop\-in=\fR\fINAME\fR +\fB\-\-drop\-in=\fR\fB\fINAME\fR\fR .RS 4 When used with \fBedit\fR, use @@ -2691,6 +2853,30 @@ is given, the currently scheduled action will be shown, which can be canceled by Added in version 254\&. .RE .PP +\fB\-\-stdin\fR +.RS 4 +When used with +\fBedit\fR, the contents of the file will be read from standard input and the editor will not be launched\&. In this mode, the old contents of the file are completely replaced\&. This is useful to "edit" unit files from scripts: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemctl edit \-\-drop\-in=limits\&.conf \-\-stdin some\-service\&.service <<EOF +[Unit] +AllowedCPUs=7,11 +EOF + +.fi +.if n \{\ +.RE +.\} +.sp +Multiple drop\-ins may be "edited" in this mode; the same contents will be written to all of them\&. +.sp +Added in version 256\&. +.RE +.PP \fB\-H\fR, \fB\-\-host=\fR .RS 4 Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by @@ -2716,12 +2902,19 @@ syntax is used either the left hand side or the right hand side may be omitted ( are implied\&. .RE .PP +\fB\-C\fR, \fB\-\-capsule=\fR +.RS 4 +Execute operation on a capsule\&. Specify a capsule name to connect to\&. See +\fBcapsule@.service\fR(5) +for details about capsules\&. +.RE +.PP \fB\-\-no\-pager\fR .RS 4 Do not pipe output into a pager\&. .RE .PP -\fB\-\-legend=\fR\fIBOOL\fR +\fB\-\-legend=\fR\fB\fIBOOL\fR\fR .RS 4 Enable or disable printing of the legend, i\&.e\&. column headers and the footer with hints\&. The legend is printed by default, unless disabled with \fB\-\-quiet\fR @@ -2749,7 +2942,7 @@ uses the return codes defined by LSB, as defined in .nr an-no-space-flag 1 .nr an-break-flag 1 .br -.B Table\ \&3.\ \&LSB return codes +.B Table\ \&4.\ \&LSB return codes .TS allbox tab(:); lB lB lB. @@ -2829,7 +3022,7 @@ Added in version 218\&. .PP \fI$SYSTEMD_LOG_LEVEL\fR .RS 4 -The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance) +The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance) \fBemerg\fR, \fBalert\fR, \fBcrit\fR, @@ -2839,7 +3032,15 @@ The maximum log level of emitted messages (messages with a higher log level, i\& \fBinfo\fR, \fBdebug\fR, or an integer in the range 0\&...7\&. See \fBsyslog\fR(3) -for more information\&. +for more information\&. Each value may optionally be prefixed with one of +\fBconsole\fR, +\fBsyslog\fR, +\fBkmsg\fR +or +\fBjournal\fR +followed by a colon to set the maximum log level for that specific log target (e\&.g\&. +\fBSYSTEMD_LOG_LEVEL=debug,console:info\fR +specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&. .RE .PP \fI$SYSTEMD_LOG_COLOR\fR @@ -2945,6 +3146,12 @@ will be ignored by the executable, and needs to be handled by the pager\&. This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&. .RE .sp +Note that setting the regular +\fI$LESS\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. +.sp See \fBless\fR(1) for more discussion\&. @@ -2956,6 +3163,12 @@ Override the charset passed to \fBless\fR (by default "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&. +.sp +Note that setting the regular +\fI$LESSCHARSET\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. .RE .PP \fI$SYSTEMD_PAGERSECURE\fR @@ -3011,17 +3224,7 @@ and other conditions\&. .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBjournalctl\fR(1), -\fBloginctl\fR(1), -\fBmachinectl\fR(1), -\fBsystemd.unit\fR(5), -\fBsystemd.resource-control\fR(5), -\fBsystemd.special\fR(7), -\fBwall\fR(1), -\fBsystemd.preset\fR(5), -\fBsystemd.generator\fR(7), -\fBglob\fR(7) +\fBsystemd\fR(1), \fBjournalctl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.special\fR(7), \fBwall\fR(1), \fBsystemd.preset\fR(5), \fBsystemd.generator\fR(7), \fBglob\fR(7) .SH "NOTES" .IP " 1." 4 Boot Loader Specification |