From 78e9bb837c258ac0ec7712b3d612cc2f407e731e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 05:50:42 +0200 Subject: Merging upstream version 256. Signed-off-by: Daniel Baumann --- man/systemctl.xml | 426 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 265 insertions(+), 161 deletions(-) (limited to 'man/systemctl.xml') diff --git a/man/systemctl.xml b/man/systemctl.xml index 9bdd882..70fd91f 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1,6 +1,6 @@ %entities; ]> @@ -350,7 +350,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err "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's + on disk, which might not match the system manager's understanding of these units if any unit files were updated on disk and the daemon-reload command wasn't issued since. @@ -513,7 +513,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - + @@ -569,6 +569,51 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err 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. + + + Possible values for <option>--what=</option> + + + + + + Value + Unit Setting + + + + + runtime + RuntimeDirectory= + + + state + StateDirectory= + + + cache + CacheDirectory= + + + logs + LogsDirectory= + + + configuration + ConfigurationDirectory= + + + fdstore + FileDescriptorStorePreserve= + + + all + All of the above + + + +
+ @@ -1066,8 +1111,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - - + @@ -1171,7 +1215,6 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err enable. - @@ -1179,38 +1222,40 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err edit UNIT… - Edit a drop-in snippet or a whole replacement file if - 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. - Depending on whether (the default), - , or 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. + Depending on whether (the default), , or + 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. + + 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 systemctl daemon-reload --system or + systemctl daemon-reload --user. For edit --global, 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). + + If is specified, a replacement for the main unit file will be + created or edited. Otherwise, a drop-in file will be created or edited. If is specified, the given drop-in file name will be used instead of the default override.conf. - If is specified, this will copy the - original units instead of creating drop-in files. - - If is specified and any units do - not already exist, new unit files will be opened for editing. + The unit must exist, i.e. its main unit file must be present. If + is specified, this requirement is ignored and a new unit may be created (with + ), or a drop-in for a nonexistent unit may be created. If is specified, the changes will be made temporarily in /run/ and they will be lost on the next reboot. + If is specified, the new contents will be read from standard + input. In this mode, the old contents of the file are discarded. + 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 @@ -1583,7 +1628,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - + @@ -1773,6 +1818,24 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err + + sleep + + + Put the system to sleep, through suspend, hibernate, + hybrid-sleep, or suspend-then-hibernate. The sleep operation + to use is automatically selected by + systemd-logind.service8. + By default, suspend-then-hibernate is used, and falls back to suspend + and then hibernate if not supported. Refer to SleepOperation= + setting in logind.conf5 + 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. + + + + + suspend @@ -1780,6 +1843,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err 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. + + If is specified, and systemd-logind returned + error for the operation, the error will be ignored and the operation will be tried again directly + through starting the target unit. @@ -1790,6 +1857,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err 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. + + This command honors in the same way as suspend. @@ -1801,6 +1870,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err 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. + This command honors in the same way as suspend. + @@ -1809,12 +1880,15 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err suspend-then-hibernate - Suspend the system and hibernate it after the delay specified in systemd-sleep.conf. - 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. + 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. - + This command honors in the same way as suspend. + + @@ -1855,7 +1929,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err for more details. The patterns are matched against the primary names of units currently in memory, and patterns which do not match anything are silently skipped. For example: - # systemctl stop sshd@*.service + # systemctl stop "sshd@*.service" will stop all sshd@.service instances. Note that alias names of units, and units that aren't in memory are not considered for glob expansion. @@ -1944,12 +2018,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - Equivalent to , i.e. shows the - value of the property without the property name or =. Note that using - once will also affect all properties listed with - /. - - + + @@ -2091,7 +2161,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err When printing properties with show, only print the value, and skip the property name and =. Also see option above. - + @@ -2101,7 +2171,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err When showing sockets, show the type of the socket. - + @@ -2109,72 +2179,72 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - 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, - flush, - triggering, or - restart-dependencies. 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 (or even being enqueued - while the irreversible jobs are still pending). Irreversible - jobs can still be cancelled using the cancel - command. This job mode should be used on any transaction which - pulls in shutdown.target. - - 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 honored. - - triggering may only be used with - systemctl stop. In this mode, the specified - unit and any active units that trigger it are stopped. See the - discussion of - Triggers= in systemd.unit5 - for more information about triggering units. - - restart-dependencies may only be used with - systemctl start. In this mode, dependencies of - the specified unit will receive restart propagation, as if a restart - job had been enqueued for the unit. - - + 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, + flush, + triggering, or + restart-dependencies. 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 (or even being enqueued + while the irreversible jobs are still pending). Irreversible + jobs can still be cancelled using the cancel + command. This job mode should be used on any transaction which + pulls in shutdown.target. + + 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 honored. + + triggering may only be used with + systemctl stop. In this mode, the specified + unit and any active units that trigger it are stopped. See the + discussion of + Triggers= in systemd.unit5 + for more information about triggering units. + + restart-dependencies may only be used with + systemctl start. In this mode, dependencies of + the specified unit will receive restart propagation, as if a restart + job had been enqueued for the unit. + + @@ -2190,7 +2260,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err run as effect of the enqueued jobs might request further jobs to be pulled in. This means that completion of the listed jobs might ultimately entail more jobs than the listed ones. - + @@ -2237,7 +2307,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err Shortcut for . - + @@ -2289,7 +2359,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err when a stop-ped, disable-d, or mask-ed - unit still has active triggering units. + unit still has active triggering units, + + + when a unit file is changed and requires daemon-reload. @@ -2315,14 +2388,16 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - Synchronously wait for started units to terminate again. - This option may not be combined with . - 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. + When used with start or restart, synchronously wait for + started units to terminate again. This option may not be combined with . + 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. - When used with is-system-running, wait - until the boot process is completed before returning. + When used with is-system-running, wait until the boot process is completed + before returning. + + When used with kill, wait until the signalled units terminate. Note that + this will wait forever if any given unit never terminates. @@ -2414,12 +2489,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err &UMOUNT_PATH;), but no main process is defined. If omitted, defaults to . - + - INT + If used with the kill command, enqueues a signal along with the specified integer value parameter to the specified process(es). This operation is only available for @@ -2458,7 +2533,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err FileDescriptorStorePreserve= option is enabled, since the file descriptor store is otherwise cleaned automatically when the unit is stopped. - + @@ -2467,22 +2542,28 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - When used with enable, overwrite - any existing conflicting symlinks. - - When used with edit, create all of the - specified units which do not already exist. - - When used with halt, poweroff, reboot or - kexec, 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 is specified - twice for these operations (with the exception of kexec), they will be executed - immediately, without terminating any processes or unmounting any file systems. Warning: specifying - twice with any of these operations might result in data loss. Note that when - is specified twice the selected operation is executed by - systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager has crashed. + When used with enable, overwrite any existing conflicting symlinks. + + When used with edit, create all of the specified units which do not already exist. + + When used with suspend, hibernate, hybrid-sleep, + or suspend-then-hibernate, the error returned by systemd-logind + will be ignored, and the operation will be performed directly through starting the corresponding units. + + + When used with halt, poweroff, reboot, + or kexec, 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 + is specified twice for these operations (with the exception of kexec), they will + be executed immediately, without terminating any processes or unmounting any file systems. + + + Specifying twice with any of these operations might result in data loss. + Note that when is specified twice the selected operation is executed by + systemctl itself, and the system manager is not contacted. This means the command + should succeed even when the system manager has crashed. + @@ -2494,7 +2575,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err short message explaining the reason for the operation. The message will be logged together with the default shutdown message. - + @@ -2508,7 +2589,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err or stop operation is only carried out when the respective enable or disable operation has been successful. - + @@ -2575,7 +2656,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err enabled according to the preset rules, or only enabled, or only disabled. - + @@ -2612,7 +2693,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err setup interface for the next boot. Note that this functionality is not available on all systems. - + @@ -2626,7 +2707,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err in order to disable the menu timeout. Note that not all boot loaders support this functionality. - + @@ -2640,7 +2721,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err or help in order to list available entries. Note that not all boot loaders support this functionality. - + @@ -2648,11 +2729,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - This switch is used with reboot. 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. + This switch is used with reboot. 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. - + @@ -2665,7 +2747,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err the output is printed as a list instead of a tree, and the bullet circles are omitted. - + @@ -2723,7 +2805,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - + @@ -2762,7 +2844,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - NAME + When used with edit, use NAME as the drop-in file name instead of override.conf. @@ -2782,12 +2864,34 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err section "PARSING TIMESTAMPS". Specially, if show is given, the currently scheduled action will be shown, which can be canceled by passing an empty string or cancel. - + + + + + + + + + When used with edit, 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: + + $ systemctl edit --drop-in=limits.conf --stdin some-service.service <<EOF +[Unit] +AllowedCPUs=7,11 +EOF + + + Multiple drop-ins may be "edited" in this mode; the same contents will be written to all of + them. + + + @@ -2888,19 +2992,19 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err See Also - - systemd1, - journalctl1, - loginctl1, - machinectl1, - systemd.unit5, - systemd.resource-control5, - systemd.special7, - wall1, - systemd.preset5, - systemd.generator7, - glob7 - + + systemd1 + journalctl1 + loginctl1 + machinectl1 + systemd.unit5 + systemd.resource-control5 + systemd.special7 + wall1 + systemd.preset5 + systemd.generator7 + glob7 + -- cgit v1.2.3