diff options
Diffstat (limited to 'src')
63 files changed, 11694 insertions, 0 deletions
diff --git a/src/grp-system/systemctl/.gitignore b/src/grp-system/systemctl/.gitignore new file mode 100644 index 0000000000..ebd59d3c9e --- /dev/null +++ b/src/grp-system/systemctl/.gitignore @@ -0,0 +1,2 @@ +/systemctl +/_systemctl diff --git a/src/grp-system/systemctl/systemctl.completion.bash.in b/src/grp-system/systemctl/systemctl.completion.bash.in new file mode 100644 index 0000000000..6f2b3f122c --- /dev/null +++ b/src/grp-system/systemctl/systemctl.completion.bash.in @@ -0,0 +1,284 @@ +# systemctl(1) completion -*- shell-script -*- +# +# This file is part of systemd. +# +# Copyright 2010 Ran Benita +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# systemd is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public License +# along with systemd; If not, see <http://www.gnu.org/licenses/>. + +__systemctl() { + local mode=$1; shift 1 + systemctl $mode --full --no-legend "$@" +} + +__systemd_properties() { + local mode=$1 + { __systemctl $mode show --all; + @rootlibexecdir@/systemd --dump-configuration-items; } | + while IFS='=' read -r key value; do + [[ $value ]] && echo "$key" + done +} + +__contains_word () { + local w word=$1; shift + for w in "$@"; do + [[ $w = "$word" ]] && return + done +} + +__filter_units_by_property () { + local mode=$1 property=$2 value=$3 ; shift 3 + local units=("$@") + local props + IFS=$'\n' read -rd '' -a props < \ + <(__systemctl $mode show --property "$property" -- "${units[@]}") + for ((i=0; $i < ${#units[*]}; i++)); do + if [[ "${props[i]}" = "$property=$value" ]]; then + echo " ${units[i]}" + fi + done +} + +__get_all_units () { { __systemctl $1 list-unit-files; __systemctl $1 list-units --all; } \ + | { while read -r a b; do [[ $a =~ @\. ]] || echo " $a"; done; }; } +__get_template_names () { __systemctl $1 list-unit-files \ + | { while read -r a b; do [[ $a =~ @\. ]] && echo " ${a%%@.*}@"; done; }; } + +__get_active_units () { __systemctl $1 list-units \ + | { while read -r a b; do echo " $a"; done; }; } +__get_startable_units () { + # find startable inactive units + __filter_units_by_property $mode ActiveState inactive $( + __filter_units_by_property $mode CanStart yes $( + __systemctl $mode list-unit-files --state enabled,disabled,static | \ + { while read -r a b; do [[ $a =~ @\. ]] || echo " $a"; done; } + __systemctl $mode list-units --state inactive,failed | \ + { while read -r a b; do echo " $a"; done; } )) +} +__get_restartable_units () { + # filter out masked and not-found + __filter_units_by_property $mode CanStart yes $( + __systemctl $mode list-unit-files --state enabled,disabled,static | \ + { while read -r a b; do [[ $a =~ @\. ]] || echo " $a"; done; } + __systemctl $mode list-units | \ + { while read -r a b; do echo " $a"; done; } ) +} +__get_failed_units () { __systemctl $1 list-units \ + | { while read -r a b c d; do [[ $c == "failed" ]] && echo " $a"; done; }; } +__get_enabled_units () { __systemctl $1 list-unit-files \ + | { while read -r a b c ; do [[ $b == "enabled" ]] && echo " $a"; done; }; } +__get_disabled_units () { __systemctl $1 list-unit-files \ + | { while read -r a b c ; do [[ $b == "disabled" ]] && echo " $a"; done; }; } +__get_masked_units () { __systemctl $1 list-unit-files \ + | { while read -r a b c ; do [[ $b == "masked" ]] && echo " $a"; done; }; } +__get_all_unit_files () { { __systemctl $1 list-unit-files; } | { while read -r a b; do echo " $a"; done; }; } + +__get_machines() { + local a b + { machinectl list-images --no-legend --no-pager; machinectl list --no-legend --no-pager; } | \ + { while read a b; do echo " $a"; done; } +} + +_systemctl () { + local cur=${COMP_WORDS[COMP_CWORD]} prev=${COMP_WORDS[COMP_CWORD-1]} + local i verb comps mode + + local -A OPTS=( + [STANDALONE]='--all -a --reverse --after --before --defaults --force -f --full -l --global + --help -h --no-ask-password --no-block --no-legend --no-pager --no-reload --no-wall + --quiet -q --privileged -P --system --user --version --runtime --recursive -r --firmware-setup + --show-types -i --ignore-inhibitors --plain' + [ARG]='--host -H --kill-who --property -p --signal -s --type -t --state --job-mode --root + --preset-mode -n --lines -o --output -M --machine' + ) + + if __contains_word "--user" ${COMP_WORDS[*]}; then + mode=--user + elif __contains_word "--global" ${COMP_WORDS[*]}; then + mode=--user + else + mode=--system + fi + + if __contains_word "$prev" ${OPTS[ARG]}; then + case $prev in + --signal|-s) + _signals + return + ;; + --type|-t) + comps=$(__systemctl $mode -t help) + ;; + --state) + comps=$(__systemctl $mode --state=help) + ;; + --job-mode) + comps='fail replace replace-irreversibly isolate + ignore-dependencies ignore-requirements flush' + ;; + --kill-who) + comps='all control main' + ;; + --root) + comps=$(compgen -A directory -- "$cur" ) + compopt -o filenames + ;; + --host|-H) + comps=$(compgen -A hostname) + ;; + --property|-p) + comps=$(__systemd_properties $mode) + ;; + --preset-mode) + comps='full enable-only disable-only' + ;; + --output|-o) + comps='short short-iso short-precise short-monotonic verbose export json + json-pretty json-sse cat' + ;; + --machine|-M) + comps=$( __get_machines ) + ;; + esac + COMPREPLY=( $(compgen -W '$comps' -- "$cur") ) + return 0 + fi + + if [[ "$cur" = -* ]]; then + COMPREPLY=( $(compgen -W '${OPTS[*]}' -- "$cur") ) + return 0 + fi + + local -A VERBS=( + [ALL_UNITS]='is-active is-failed is-enabled status show cat mask preset help list-dependencies edit set-property' + [ENABLED_UNITS]='disable' + [DISABLED_UNITS]='enable' + [REENABLABLE_UNITS]='reenable' + [FAILED_UNITS]='reset-failed' + [STARTABLE_UNITS]='start' + [STOPPABLE_UNITS]='stop condstop kill try-restart condrestart' + [ISOLATABLE_UNITS]='isolate' + [RELOADABLE_UNITS]='reload condreload try-reload-or-restart force-reload' + [RESTARTABLE_UNITS]='restart reload-or-restart' + [TARGET_AND_UNITS]='add-wants add-requires' + [MASKED_UNITS]='unmask' + [JOBS]='cancel' + [ENVS]='set-environment unset-environment' + [STANDALONE]='daemon-reexec daemon-reload default + emergency exit halt hibernate hybrid-sleep kexec list-jobs + list-sockets list-timers list-units list-unit-files poweroff + reboot rescue show-environment suspend get-default + is-system-running' + [FILE]='link switch-root' + [TARGETS]='set-default' + ) + + for ((i=0; i < COMP_CWORD; i++)); do + if __contains_word "${COMP_WORDS[i]}" ${VERBS[*]} && + ! __contains_word "${COMP_WORDS[i-1]}" ${OPTS[ARG]}; then + verb=${COMP_WORDS[i]} + break + fi + done + + if [[ -z $verb ]]; then + comps="${VERBS[*]}" + + elif __contains_word "$verb" ${VERBS[ALL_UNITS]}; then + comps=$( __get_all_units $mode ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[ENABLED_UNITS]}; then + comps=$( __get_enabled_units $mode ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[DISABLED_UNITS]}; then + comps=$( __get_disabled_units $mode; + __get_template_names $mode) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[REENABLABLE_UNITS]}; then + comps=$( __get_disabled_units $mode; + __get_enabled_units $mode; + __get_template_names $mode) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[STARTABLE_UNITS]}; then + comps=$( __get_startable_units $mode; + __get_template_names $mode) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[RESTARTABLE_UNITS]}; then + comps=$( __get_restartable_units $mode; + __get_template_names $mode) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[STOPPABLE_UNITS]}; then + comps=$( __filter_units_by_property $mode CanStop yes \ + $( __get_active_units $mode ) ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[RELOADABLE_UNITS]}; then + comps=$( __filter_units_by_property $mode CanReload yes \ + $( __get_active_units $mode ) ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[ISOLATABLE_UNITS]}; then + comps=$( __filter_units_by_property $mode AllowIsolate yes \ + $( __get_all_units $mode ) ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[FAILED_UNITS]}; then + comps=$( __get_failed_units $mode ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[MASKED_UNITS]}; then + comps=$( __get_masked_units $mode ) + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[TARGET_AND_UNITS]}; then + if __contains_word "$prev" ${VERBS[TARGET_AND_UNITS]} \ + || __contains_word "$prev" ${OPTS[STANDALONE]}; then + comps=$( __systemctl $mode list-unit-files --type target --all \ + | { while read -r a b; do echo " $a"; done; } ) + else + comps=$( __get_all_unit_files $mode ) + fi + compopt -o filenames + + elif __contains_word "$verb" ${VERBS[STANDALONE]}; then + comps='' + + elif __contains_word "$verb" ${VERBS[JOBS]}; then + comps=$( __systemctl $mode list-jobs | { while read -r a b; do echo " $a"; done; } ) + + elif __contains_word "$verb" ${VERBS[ENVS]}; then + comps=$( __systemctl $mode show-environment \ + | while read -r line; do echo " ${line%%=*}=";done ) + compopt -o nospace + + elif __contains_word "$verb" ${VERBS[FILE]}; then + comps=$( compgen -A file -- "$cur" ) + compopt -o filenames + elif __contains_word "$verb" ${VERBS[TARGETS]}; then + comps=$( __systemctl $mode list-unit-files --type target --full --all \ + | { while read -r a b; do echo " $a"; done; } ) + fi + + COMPREPLY=( $(compgen -o filenames -W '$comps' -- "$cur") ) + return 0 +} + +complete -F _systemctl systemctl diff --git a/src/grp-system/systemctl/systemctl.completion.zsh.in b/src/grp-system/systemctl/systemctl.completion.zsh.in new file mode 100644 index 0000000000..44c31b7833 --- /dev/null +++ b/src/grp-system/systemctl/systemctl.completion.zsh.in @@ -0,0 +1,391 @@ +#compdef systemctl + +(( $+functions[_systemctl_command] )) || _systemctl_command() +{ + local -a _systemctl_cmds + _systemctl_cmds=( + "list-sockets:List sockets" + "list-timers:List timers" + "list-units:List units" + "start:Start (activate) one or more units" + "stop:Stop (deactivate) one or more units" + "reload:Reload one or more units" + "restart:Start or restart one or more units" + "condrestart:Restart one or more units if active" + "try-restart:Restart one or more units if active" + "reload-or-restart:Reload one or more units if possible, otherwise start or restart" + "force-reload:Reload one or more units if possible, otherwise restart if active" + "hibernate:Hibernate the system" + "hybrid-sleep:Hibernate and suspend the system" + "try-reload-or-restart:Reload one or more units if possible, otherwise restart if active" + "isolate:Start one unit and stop all others" + "kill:Send signal to processes of a unit" + "is-active:Check whether units are active" + "is-failed:Check whether units are failed" + "status:Show runtime status of one or more units" + "show:Show properties of one or more units/jobs or the manager" + "cat:Show the source unit files and drop-ins" + "reset-failed:Reset failed state for all, one, or more units" + "list-unit-files:List installed unit files" + "enable:Enable one or more unit files" + "disable:Disable one or more unit files" + "reenable:Reenable one or more unit files" + "preset:Enable/disable one or more unit files based on preset configuration" + "set-default:Set the default target" + "get-default:Query the default target" + "edit:Edit one or more unit files" + "is-system-running:Query overall status of the system" + "help:Show documentation for specified units" + "list-dependencies:Show unit dependency tree" + "mask:Mask one or more units" + "unmask:Unmask one or more units" + "link:Link one or more units files into the search path" + "is-enabled:Check whether unit files are enabled" + "list-jobs:List jobs" + "cancel:Cancel all, one, or more jobs" + "show-environment:Dump environment" + "set-environment:Set one or more environment variables" + "unset-environment:Unset one or more environment variables" + "daemon-reload:Reload systemd manager configuration" + "daemon-reexec:Reexecute systemd manager" + "default:Enter system default mode" + "rescue:Enter system rescue mode" + "emergency:Enter system emergency mode" + "halt:Shut down and halt the system" + "suspend:Suspend the system" + "poweroff:Shut down and power-off the system" + "reboot:Shut down and reboot the system" + "kexec:Shut down and reboot the system with kexec" + "exit:Ask for user instance termination" + "switch-root:Change root directory" + ) + + if (( CURRENT == 1 )); then + _describe -t commands 'systemctl command' _systemctl_cmds || compadd "$@" + else + local curcontext="$curcontext" expl + + cmd="${${_systemctl_cmds[(r)$words[1]:*]%%:*}}" + # Deal with any aliases + case $cmd in + condrestart) cmd="try-restart";; + force-reload) cmd="try-reload-or-restart";; + esac + + if (( $#cmd )); then + curcontext="${curcontext%:*:*}:systemctl-${cmd}:" + + local update_policy + zstyle -s ":completion:${curcontext}:" cache-policy update_policy + if [[ -z "$update_policy" ]]; then + zstyle ":completion:${curcontext}:" cache-policy _systemctl_caching_policy + fi + + _call_function ret _systemctl_$cmd || _message 'no more arguments' + else + _message "unknown systemctl command: $words[1]" + fi + return ret + fi +} + +__systemctl() +{ + systemctl $_sys_service_mgr --full --no-legend --no-pager "$@" +} + + +# Fills the unit list +_systemctl_all_units() +{ + if ( [[ ${+_sys_all_units} -eq 0 ]] || _cache_invalid SYS_ALL_UNITS ) && + ! _retrieve_cache SYS_ALL_UNITS; + then + _sys_all_units=( ${${(f)"$(__systemctl list-units --all)"}%% *} ) + _store_cache SYS_ALL_UNITS _sys_all_units + fi +} + +# Fills the unit list including all file units +_systemctl_really_all_units() +{ + local -a all_unit_files; + local -a really_all_units; + if ( [[ ${+_sys_really_all_units} -eq 0 ]] || _cache_invalid SYS_REALLY_ALL_UNITS ) && + ! _retrieve_cache SYS_REALLY_ALL_UNITS; + then + all_unit_files=( ${${(f)"$(__systemctl list-unit-files)"}%% *} ) + _systemctl_all_units + really_all_units=($_sys_all_units $all_unit_files) + _sys_really_all_units=(${(u)really_all_units}) + _store_cache SYS_REALLY_ALL_UNITS _sys_really_all_units + fi +} + +_filter_units_by_property() { + local property=$1 value=$2 ; shift ; shift + local -a units ; units=($*) + local props + for props in ${(ps:\n\n:)"$(_call_program units "$service show --no-pager --property="Id,$property" -- ${units} 2>/dev/null")"}; do + props=(${(f)props}) + if [[ "${props[2]}" = "$property=$value" ]]; then + echo -E - " ${props[1]#Id=}" + fi + done +} + +_systemctl_get_template_names() { echo -E - ${^${(M)${(f)"$(__systemctl list-unit-files)"}##*@.[^[:space:]]##}%%@.*}\@ } + + +_systemctl_active_units() {_sys_active_units=( ${${(f)"$(__systemctl list-units)"}%% *} )} + +_systemctl_startable_units(){ + _sys_startable_units=( $( _filter_units_by_property ActiveState inactive $( + _filter_units_by_property CanStart yes $( + __systemctl $mode list-unit-files --state enabled,disabled,static | \ + { while read -r a b; do [[ $a =~ @\. ]] || echo -E - " $a"; done; } + __systemctl $mode list-units --state inactive,failed | \ + { while read -r a b; do echo -E - " $a"; done; } )) ) ) +} + +_systemctl_restartable_units(){ + _sys_restartable_units=( $(_filter_units_by_property CanStart yes $( + __systemctl $mode list-unit-files --state enabled,disabled,static | \ + { while read -r a b; do [[ $a =~ @\. ]] || echo -E - " $a"; done; } + __systemctl $mode list-units | \ + { while read -r a b; do echo -E - " $a"; done; } )) ) +} + +_systemctl_failed_units() {_sys_failed_units=( ${${(f)"$(__systemctl list-units --state=failed)"}%% *} ) } +_systemctl_unit_state() { typeset -gA _sys_unit_state; _sys_unit_state=( $(__systemctl list-unit-files) ) } + +local fun +# Completion functions for ALL_UNITS +for fun in is-active is-failed is-enabled status show cat mask preset help list-dependencies edit ; do + (( $+functions[_systemctl_$fun] )) || _systemctl_$fun() + { + _systemctl_really_all_units + _wanted systemd-units expl unit \ + compadd "$@" -a - _sys_really_all_units + } +done + +# Completion functions for ENABLED_UNITS +(( $+functions[_systemctl_disable] )) || _systemctl_disable() +{ + local _sys_unit_state; _systemctl_unit_state + _wanted systemd-units expl 'enabled unit' \ + compadd "$@" - ${(k)_sys_unit_state[(R)enabled]} +} + +(( $+functions[_systemctl_reenable] )) || _systemctl_reenable() +{ + local _sys_unit_state; _systemctl_unit_state + _wanted systemd-units expl 'enabled/disabled unit' \ + compadd "$@" - ${(k)_sys_unit_state[(R)(enabled|disabled)]} $(_systemctl_get_template_names) +} + +# Completion functions for DISABLED_UNITS +(( $+functions[_systemctl_enable] )) || _systemctl_enable() +{ + local _sys_unit_state; _systemctl_unit_state + _wanted systemd-units expl 'disabled unit' \ + compadd "$@" - ${(k)_sys_unit_state[(R)disabled]} $(_systemctl_get_template_names) +} + +# Completion functions for FAILED_UNITS +(( $+functions[_systemctl_reset-failed] )) || _systemctl_reset-failed() +{ + local _sys_failed_units; _systemctl_failed_units + _wanted systemd-units expl 'failed unit' \ + compadd "$@" -a - _sys_failed_units || _message "no failed unit found" +} + +# Completion functions for STARTABLE_UNITS +(( $+functions[_systemctl_start] )) || _systemctl_start() +{ + local _sys_startable_units; _systemctl_startable_units + _wanted systemd-units expl 'startable unit' \ + compadd "$@" - ${_sys_startable_units[*]} $(_systemctl_get_template_names) +} + +# Completion functions for STOPPABLE_UNITS +for fun in stop kill try-restart condrestart ; do + (( $+functions[_systemctl_$fun] )) || _systemctl_$fun() + { + local _sys_active_units; _systemctl_active_units + _wanted systemd-units expl 'stoppable unit' \ + compadd "$@" - $( _filter_units_by_property CanStop yes \ + ${_sys_active_units[*]} ) + } +done + +# Completion functions for ISOLATABLE_UNITS +(( $+functions[_systemctl_isolate] )) || _systemctl_isolate() +{ + _systemctl_all_units + _wanted systemd-units expl 'isolatable unit' \ + compadd "$@" - $( _filter_units_by_property AllowIsolate yes \ + ${_sys_all_units[*]} ) +} + +# Completion functions for RELOADABLE_UNITS +for fun in reload try-reload-or-restart force-reload ; do + (( $+functions[_systemctl_$fun] )) || _systemctl_$fun() + { + local _sys_active_units; _systemctl_active_units + _wanted systemd-units expl 'reloadable unit' \ + compadd "$@" - $( _filter_units_by_property CanReload yes \ + ${_sys_active_units[*]} ) + } +done + +# Completion functions for RESTARTABLE_UNITS +for fun in restart reload-or-restart ; do + (( $+functions[_systemctl_$fun] )) || _systemctl_$fun() + { + local _sys_restartable_units; _systemctl_restartable_units + _wanted systemd-units expl 'restartable unit' \ + compadd "$@" - ${_sys_restartable_units[*]} $(_systemctl_get_template_names) + } +done + +# Completion functions for MASKED_UNITS +(( $+functions[_systemctl_unmask] )) || _systemctl_unmask() +{ + local _sys_unit_state; _systemctl_unit_state + _wanted systemd-units expl 'masked unit' \ + compadd "$@" - ${(k)_sys_unit_state[(R)masked]} || _message "no masked units found" +} + +# Completion functions for JOBS +(( $+functions[_systemctl_cancel] )) || _systemctl_cancel() +{ + _wanted systemd-jobs expl job \ + compadd "$@" - ${${(f)"$(__systemctl list-jobs)"}%% *} || + _message "no jobs found" +} + +# Completion functions for TARGETS +(( $+functions[_systemctl_set-default] )) || _systemctl_set-default() +{ + _wanted systemd-targets expl target \ + compadd "$@" - ${${(f)"$(__systemctl list-unit-files --type target --all)"}%% *} || + _message "no targets found" +} + +# Completion functions for ENVS +for fun in set-environment unset-environment ; do + (( $+functions[_systemctl_$fun] )) || _systemctl_$fun() + { + local fun=$0 ; fun=${fun##_systemctl_} + local suf + if [[ "${fun}" = "set-environment" ]]; then + suf='-S=' + fi + _wanted systemd-environment expl 'environment variable' \ + compadd "$@" ${suf} - ${${(f)"$(systemctl show-environment)"}%%=*} + } +done + +(( $+functions[_systemctl_link] )) || _systemctl_link() { + _sd_unit_files +} + +(( $+functions[_systemctl_switch-root] )) || _systemctl_switch-root() { + _files +} + +# no systemctl completion for: +# [STANDALONE]='daemon-reexec daemon-reload default +# emergency exit halt kexec list-jobs list-units +# list-unit-files poweroff reboot rescue show-environment' + +_systemctl_caching_policy() +{ + local _sysunits + local -a oldcache + + # rebuild if cache is more than a day old + oldcache=( "$1"(mh+1) ) + (( $#oldcache )) && return 0 + + _sysunits=(${${(f)"$(__systemctl --all)"}%% *}) + + if (( $#_sysunits )); then + for unit in $_sysunits; do + [[ "$unit" -nt "$1" ]] && return 0 + done + fi + + return 1 +} + +_unit_states() { + local -a _states + _states=("${(fo)$(__systemctl --state=help)}") + _values -s , "${_states[@]}" +} + +_unit_types() { + local -a _types + _types=("${(fo)$(__systemctl -t help)}") + _values -s , "${_types[@]}" +} + +_unit_properties() { + if ( [[ ${+_sys_all_properties} -eq 0 ]] || _cache_invalid SYS_ALL_PROPERTIES ) && + ! _retrieve_cache SYS_ALL_PROPERTIES; + then + _sys_all_properties=( ${${(M)${(f)"$(__systemctl show --all; + @rootlibexecdir@/systemd --dump-configuration-items)"}##[[:alnum:]]##=*}%%=*} + ) + _store_cache SYS_ALL_PROPRTIES _sys_all_properties + fi + _values -s , "${_sys_all_properties[@]}" +} + +_job_modes() { + local -a _modes + _modes=(fail replace replace-irreversibly isolate ignore-dependencies ignore-requirements flush) + _values -s , "${_modes[@]}" +} + +local -a _modes; _modes=("--user" "--system") +local _sys_service_mgr=${${words:*_modes}[(R)(${(j.|.)_modes})]:---system} +_arguments -s \ + {-h,--help}'[Show help]' \ + '--version[Show package version]' \ + {-t+,--type=}'[List only units of a particular type]:unit type:_unit_types' \ + '--state=[Display units in the specified state]:unit state:_unit_states' \ + '--job-mode=[Specify how to deal with other jobs]:mode:_job_modes' \ + {-p+,--property=}'[Show only properties by specific name]:unit property:_unit_properties' \ + {-a,--all}'[Show all units/properties, including dead/empty ones]' \ + '--reverse[Show reverse dependencies]' \ + '--after[Show units ordered after]' \ + '--before[Show units ordered before]' \ + {-l,--full}"[Don't ellipsize unit names on output]" \ + '--show-types[When showing sockets, show socket type]' \ + {-i,--ignore-inhibitors}'[When executing a job, ignore jobs dependencies]' \ + {-q,--quiet}'[Suppress output]' \ + '--no-block[Do not wait until operation finished]' \ + '--no-legend[Do not print a legend, i.e. the column headers and the footer with hints]' \ + '--no-pager[Do not pipe output into a pager]' \ + '--system[Connect to system manager]' \ + '--user[Connect to user service manager]' \ + "--no-wall[Don't send wall message before halt/power-off/reboot]" \ + '--global[Enable/disable unit files globally]' \ + "--no-reload[When enabling/disabling unit files, don't reload daemon configuration]" \ + '--no-ask-password[Do not ask for system passwords]' \ + '--kill-who=[Who to send signal to]:killwho:(main control all)' \ + {-s+,--signal=}'[Which signal to send]:signal:_signals' \ + {-f,--force}'[When enabling unit files, override existing symlinks. When shutting down, execute action immediately]' \ + '--root=[Enable unit files in the specified root directory]:directory:_directories' \ + '--runtime[Enable unit files only temporarily until next reboot]' \ + {-H+,--host=}'[Operate on remote host]:userathost:_sd_hosts_or_user_at_host' \ + {-P,--privileged}'[Acquire privileges before execution]' \ + {-n+,--lines=}'[Journal entries to show]:number of entries' \ + {-o+,--output=}'[Change journal output mode]:modes:_sd_outputmodes' \ + '--firmware-setup[Tell the firmware to show the setup menu on next boot]' \ + '--plain[When used with list-dependencies, print output as a list]' \ + '*::systemctl command:_systemctl_command' diff --git a/src/libudev/udev_device_get_syspath.xml b/src/libudev/udev_device_get_syspath.xml new file mode 100644 index 0000000000..b54749ed56 --- /dev/null +++ b/src/libudev/udev_device_get_syspath.xml @@ -0,0 +1,207 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_device_get_syspath" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_device_get_syspath</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_device_get_syspath</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_device_get_syspath</refname> + <refname>udev_device_get_sysname</refname> + <refname>udev_device_get_sysnum</refname> + <refname>udev_device_get_devpath</refname> + <refname>udev_device_get_devnode</refname> + <refname>udev_device_get_devnum</refname> + <refname>udev_device_get_devtype</refname> + <refname>udev_device_get_subsystem</refname> + <refname>udev_device_get_driver</refname> + <refname>udev_device_get_udev</refname> + <refname>udev_device_get_parent</refname> + <refname>udev_device_get_parent_with_subsystem_devtype</refname> + <refname>udev_device_get_is_initialized</refname> + <refname>udev_device_get_action</refname> + + <refpurpose>Query device properties</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_syspath</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_sysname</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_sysnum</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_devpath</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_devnode</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>dev_t <function>udev_device_get_devnum</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_devtype</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_subsystem</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_driver</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev *<function>udev_device_get_udev</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_get_parent</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_get_parent_with_subsystem_devtype</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + <paramdef>const char *<parameter>devtype</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_device_get_is_initialized</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_action</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add documentation.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>udev_device_get_syspath()</function>, + <function>udev_device_get_sysname()</function>, + <function>udev_device_get_sysnum()</function>, + <function>udev_device_get_devpath()</function>, + <function>udev_device_get_devnode()</function>, + <function>udev_device_get_devtype()</function>, + <function>udev_device_get_subsystem()</function>, + <function>udev_device_get_driver()</function> and + <function>udev_device_get_action()</function> return a pointer + to a constant string that describes the requested property. The + lifetime of this string is bound to the device it was requested + on. On failure, each function may return + <constant>NULL</constant>.</para> + + <para>On success, <function>udev_device_get_devnum()</function> + returns the device type of the passed device. On failure, a + device type with minor and major number set to + <constant>0</constant> is returned.</para> + + <para><function>udev_device_get_udev()</function> always returns + a valid pointer to the udev context that this device belongs + to.</para> + + <para>On success, <function>udev_device_get_parent()</function> + and + <function>udev_device_get_parent_with_subsystem_devtype()</function> + return a pointer to the parent device. No additional reference + to this device is acquired, but the child device owns a reference + to such a parent device. On failure, <constant>NULL</constant> + is returned.</para> + + <para>On success, <function>udev_device_get_is_initialized()</function> + returns either <constant>1</constant> or <constant>0</constant>, + depending on whether the passed device is initialized or not. On + failure, a negative error code is returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_device_has_tag.xml b/src/libudev/udev_device_has_tag.xml new file mode 100644 index 0000000000..480257343c --- /dev/null +++ b/src/libudev/udev_device_has_tag.xml @@ -0,0 +1,163 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_device_has_tag" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_device_has_tag</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_device_has_tag</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_device_has_tag</refname> + <refname>udev_device_get_devlinks_list_entry</refname> + <refname>udev_device_get_properties_list_entry</refname> + <refname>udev_device_get_tags_list_entry</refname> + <refname>udev_device_get_sysattr_list_entry</refname> + <refname>udev_device_get_property_value</refname> + <refname>udev_device_get_sysattr_value</refname> + <refname>udev_device_set_sysattr_value</refname> + + <refpurpose>Retrieve or set device attributes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_device_get_devlinks_list_entry</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_device_get_properties_list_entry</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_device_get_tags_list_entry</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_device_get_sysattr_list_entry</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_property_value</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>key</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_device_has_tag</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>tag</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_device_get_sysattr_value</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>sysattr</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_device_set_sysattr_value</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + <paramdef>const char *<parameter>sysattr</parameter></paramdef> + <paramdef>const char *<parameter>value</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_device_get_devlinks_list_entry()</function>, + <function>udev_device_get_properties_list_entry()</function>, + <function>udev_device_get_tags_list_entry()</function> and + <function>udev_device_get_sysattr_list_entry()</function> return + a pointer to the first entry of the retrieved list. If that list + is empty, or if an error occurred, <constant>NULL</constant> is + returned.</para> + + <para>On success, + <function>udev_device_get_property_value()</function> and + <function>udev_device_get_sysattr_value()</function> return a + pointer to a constant string of the requested value. On error, + <constant>NULL</constant> is returned.</para> + + <para>On success, + <function>udev_device_set_sysattr_value()</function> returns + an integer greater than, or equal to, <constant>0</constant>. + On failure, a negative error code is returned.</para> + + <para>On success, <function>udev_device_has_tag()</function> + returns <constant>1</constant> or <constant>0</constant>, + depending on whether the device has the given tag or not. + On failure, a negative error code is returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_device_new_from_syspath.xml b/src/libudev/udev_device_new_from_syspath.xml new file mode 100644 index 0000000000..0bb71c8e91 --- /dev/null +++ b/src/libudev/udev_device_new_from_syspath.xml @@ -0,0 +1,214 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_device_new_from_syspath" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_device_new_from_syspath</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_device_new_from_syspath</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_device_new_from_syspath</refname> + <refname>udev_device_new_from_devnum</refname> + <refname>udev_device_new_from_subsystem_sysname</refname> + <refname>udev_device_new_from_device_id</refname> + <refname>udev_device_new_from_environment</refname> + <refname>udev_device_ref</refname> + <refname>udev_device_unref</refname> + + <refpurpose>Create, acquire and release a udev device object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + <paramdef>const char *<parameter>syspath</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>dev_t <parameter>devnum</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + <paramdef>const char *<parameter>sysname</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + <paramdef>const char *<parameter>id</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef> + <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>udev_device_new_from_syspath</function>, + <function>udev_device_new_from_devnum</function>, + <function>udev_device_new_from_subsystem_sysname</function>, + <function>udev_device_new_from_device_id</function>, and + <function>udev_device_new_from_environment</function> + allocate a new udev device object and returns a pointer to it. This + object is opaque and must not be accessed by the caller via different + means than functions provided by libudev. Initially, the reference count + of the device is 1. You can acquire further references, and drop + gained references via <function>udev_device_ref()</function> and + <function>udev_device_unref()</function>. Once the reference count hits 0, + the device object is destroyed and freed.</para> + + <para><function>udev_device_new_from_syspath</function>, + <function>udev_device_new_from_devnum</function>, + <function>udev_device_new_from_subsystem_sysname</function>, and + <function>udev_device_new_from_device_id</function> + create the device object based on information found in + <filename>/sys</filename>, annotated with properties from the udev-internal + device database. A syspath is any subdirectory of <filename>/sys</filename>, + with the restriction that a subdirectory of <filename>/sys/devices</filename> + (or a symlink to one) represents a real device and as such must contain + a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function> + takes a device type, which can be <constant>b</constant> for block devices or + <constant>c</constant> for character devices, as well as a devnum (see + <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + <function>udev_device_new_from_subsystem_sysname</function> looks up devices based + on the provided subsystem and sysname + (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + and <function>udev_device_new_from_device_id</function> looks up devices based on the provided + device ID, which is a special string in one of the following four forms: + <table> + <title>Device ID strings</title> + + <tgroup cols='2'> + <colspec colname='example' /> + <colspec colname='explanation' /> + <thead><row> + <entry>Example</entry> + <entry>Explanation</entry> + </row></thead> + <tbody> + <row><entry><varname>b8:2</varname></entry> + <entry>block device major:minor</entry></row> + + <row><entry><varname>c128:1</varname></entry> + <entry>char device major:minor</entry></row> + + <row><entry><varname>n3</varname></entry> + <entry>network device ifindex</entry></row> + + <row><entry><varname>+sound:card29</varname></entry> + <entry>kernel driver core subsystem:device name</entry></row> + </tbody> + </tgroup> + </table> + </para> + + <para><function>udev_device_new_from_environment</function> + creates a device from the current environment (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + Each key-value pair is interpreted in the same way as if it was + received in an uevent (see + <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + The keys <constant>DEVPATH</constant>, <constant>SUBSYSTEM</constant>, + <constant>ACTION</constant>, and <constant>SEQNUM</constant> are mandatory.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>udev_device_new_from_syspath()</function>, + <function>udev_device_new_from_devnum()</function>, + <function>udev_device_new_from_subsystem_sysname()</function>, + <function>udev_device_new_from_device_id()</function> and + <function>udev_device_new_from_environment()</function> return a + pointer to the allocated udev device. On failure, + <constant>NULL</constant> is returned, + and <varname>errno</varname> is set appropriately. + <function>udev_device_ref()</function> returns the argument + that it was passed, unmodified. + <function>udev_device_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_enumerate_add_match_subsystem.xml b/src/libudev/udev_enumerate_add_match_subsystem.xml new file mode 100644 index 0000000000..5acce00bb0 --- /dev/null +++ b/src/libudev/udev_enumerate_add_match_subsystem.xml @@ -0,0 +1,163 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_enumerate_add_match_subsystem" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_enumerate_add_match_subsystem</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_enumerate_add_match_subsystem</refname> + <refname>udev_enumerate_add_nomatch_subsystem</refname> + <refname>udev_enumerate_add_match_sysattr</refname> + <refname>udev_enumerate_add_nomatch_sysattr</refname> + <refname>udev_enumerate_add_match_property</refname> + <refname>udev_enumerate_add_match_sysname</refname> + <refname>udev_enumerate_add_match_tag</refname> + <refname>udev_enumerate_add_match_parent</refname> + <refname>udev_enumerate_add_match_is_initialized</refname> + + <refpurpose>Modify filters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_subsystem</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_nomatch_subsystem</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_sysattr</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>sysattr</parameter></paramdef> + <paramdef>const char *<parameter>value</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_nomatch_sysattr</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>sysattr</parameter></paramdef> + <paramdef>const char *<parameter>value</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_property</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>property</parameter></paramdef> + <paramdef>const char *<parameter>value</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_sysname</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>sysname</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_tag</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>tag</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_parent</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>struct udev_device *<parameter>parent</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_match_is_initialized</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_enumerate_add_match_subsystem</function>, + <function>udev_enumerate_add_nomatch_subsystem</function>, + <function>udev_enumerate_add_match_sysattr</function>, + <function>udev_enumerate_add_nomatch_sysattr</function>, + <function>udev_enumerate_add_match_property</function>, + <function>udev_enumerate_add_match_sysname</function>, + <function>udev_enumerate_add_match_tag</function>, + <function>udev_enumerate_add_match_parent</function> and + <function>udev_enumerate_add_match_is_initialized</function> + return an integer greater than, or equal to, + <constant>0</constant>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_scan_devices</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_enumerate_new.xml b/src/libudev/udev_enumerate_new.xml new file mode 100644 index 0000000000..b5856c5577 --- /dev/null +++ b/src/libudev/udev_enumerate_new.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_enumerate_new" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_enumerate_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_enumerate_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_enumerate_new</refname> + <refname>udev_enumerate_ref</refname> + <refname>udev_enumerate_unref</refname> + + <refpurpose>Create, acquire and release a udev enumerate object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_enumerate *<function>udev_enumerate_new</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_enumerate *<function>udev_enumerate_ref</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_enumerate *<function>udev_enumerate_unref</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>udev_enumerate_new()</function> returns a + pointer to the allocated udev monitor. On failure, + <constant>NULL</constant> is returned. + <function>udev_enumerate_ref()</function> returns the argument + that it was passed, unmodified. + <function>udev_enumerate_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_scan_devices</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_enumerate_scan_devices.xml b/src/libudev/udev_enumerate_scan_devices.xml new file mode 100644 index 0000000000..e0b6bfba32 --- /dev/null +++ b/src/libudev/udev_enumerate_scan_devices.xml @@ -0,0 +1,133 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_enumerate_scan_devices" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_enumerate_scan_devices</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_enumerate_scan_devices</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_enumerate_scan_devices</refname> + <refname>udev_enumerate_scan_subsystems</refname> + <refname>udev_enumerate_get_list_entry</refname> + <refname>udev_enumerate_add_syspath</refname> + <refname>udev_enumerate_get_udev</refname> + + <refpurpose>Query or modify a udev enumerate object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>udev_enumerate_scan_devices</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_scan_subsystems</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_enumerate_get_list_entry</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_enumerate_add_syspath</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + <paramdef>const char *<parameter>syspath</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev *<function>udev_enumerate_get_udev</function></funcdef> + <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_enumerate_scan_devices()</function>, + <function>udev_enumerate_scan_subsystems()</function> and + <function>udev_enumerate_add_syspath()</function> + return an integer greater than, or equal to, + <constant>0</constant>.</para> + + <para>On success, + <function>udev_enumerate_get_list_entry()</function> + returns a pointer to the first entry in the list of found + devices. If the list is empty, or on failure, + <constant>NULL</constant> is returned.</para> + + <para><function>udev_enumerate_get_udev()</function> always + returns a pointer to the udev context that this enumerated + object is associated with.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_list_entry.xml b/src/libudev/udev_list_entry.xml new file mode 100644 index 0000000000..a1b531d52a --- /dev/null +++ b/src/libudev/udev_list_entry.xml @@ -0,0 +1,123 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_list_entry" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_list_entry</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_list_entry</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_list_entry</refname> + <refname>udev_list_entry_get_next</refname> + <refname>udev_list_entry_get_by_name</refname> + <refname>udev_list_entry_get_name</refname> + <refname>udev_list_entry_get_value</refname> + + <refpurpose>Iterate and access udev lists</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_list_entry_get_next</function></funcdef> + <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_list_entry *<function>udev_list_entry_get_by_name</function></funcdef> + <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_list_entry_get_name</function></funcdef> + <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char *<function>udev_list_entry_get_value</function></funcdef> + <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_list_entry_get_next()</function> and + <function>udev_list_entry_get_by_name()</function> return + a pointer to the requested list entry. If no such entry can + be found, or on failure, <constant>NULL</constant> is + returned.</para> + + <para>On success, + <function>udev_list_entry_get_name()</function> and + <function>udev_list_entry_get_value()</function> return a + pointer to a constant string representing the requested value. + The string is bound to the lifetime of the list entry itself. + On failure, <constant>NULL</constant> is returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_monitor_filter_update.xml b/src/libudev/udev_monitor_filter_update.xml new file mode 100644 index 0000000000..f129595618 --- /dev/null +++ b/src/libudev/udev_monitor_filter_update.xml @@ -0,0 +1,122 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_monitor_filter_update" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_monitor_filter_update</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_monitor_filter_update</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_monitor_filter_update</refname> + <refname>udev_monitor_filter_remove</refname> + <refname>udev_monitor_filter_add_match_subsystem_devtype</refname> + <refname>udev_monitor_filter_add_match_tag</refname> + + <refpurpose>Modify filters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>udev_monitor_filter_update</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_filter_remove</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_filter_add_match_subsystem_devtype</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + <paramdef>const char *<parameter>subsystem</parameter></paramdef> + <paramdef>const char *<parameter>devtype</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_filter_add_match_tag</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + <paramdef>const char *<parameter>tag</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_monitor_filter_update()</function>, + <function>udev_monitor_filter_remove()</function>, + <function>udev_monitor_filter_add_match_subsystem_devtype()</function> + and + <function>udev_monitor_filter_add_match_tag()</function> + return an integer greater than, or equal to, + <constant>0</constant>. On failure, a negative error code is + returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_monitor_new_from_netlink.xml b/src/libudev/udev_monitor_new_from_netlink.xml new file mode 100644 index 0000000000..d73a4acaec --- /dev/null +++ b/src/libudev/udev_monitor_new_from_netlink.xml @@ -0,0 +1,113 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_monitor_new_from_netlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_monitor_new_from_netlink</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_monitor_new_from_netlink</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_monitor_new_from_netlink</refname> + <refname>udev_monitor_ref</refname> + <refname>udev_monitor_unref</refname> + + <refpurpose>Create, acquire and release a udev monitor object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_monitor *<function>udev_monitor_new_from_netlink</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_monitor *<function>udev_monitor_ref</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev_monitor *<function>udev_monitor_unref</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_monitor_new_from_netlink()</function> returns a + pointer to the allocated udev monitor. On failure, + <constant>NULL</constant> is returned. + <function>udev_monitor_ref()</function> returns the argument + that it was passed, unmodified. + <function>udev_monitor_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_filter_update</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_monitor_receive_device.xml b/src/libudev/udev_monitor_receive_device.xml new file mode 100644 index 0000000000..7e842f88df --- /dev/null +++ b/src/libudev/udev_monitor_receive_device.xml @@ -0,0 +1,137 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_monitor_receive_device" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_monitor_receive_device</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_monitor_receive_device</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_monitor_receive_device</refname> + <refname>udev_monitor_enable_receiving</refname> + <refname>udev_monitor_set_receive_buffer_size</refname> + <refname>udev_monitor_get_fd</refname> + <refname>udev_monitor_get_udev</refname> + + <refpurpose>Query and modify device monitor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev_device *<function>udev_monitor_receive_device</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_enable_receiving</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_set_receive_buffer_size</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + <paramdef>int <parameter>size</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>udev_monitor_get_fd</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev *<function>udev_monitor_get_udev</function></funcdef> + <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <!--<refsect1> + <title>Description</title> + + <para>XXX: Add short description.</para> + </refsect1>--> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>udev_monitor_receive_device()</function> returns a + pointer to a newly referenced device that was received via the + monitor. The caller is responsible to drop this reference when + done. On failure, <constant>NULL</constant> is returned.</para> + + <para>On success, + <function>udev_monitor_enable_receiving()</function> and + <function>udev_monitor_set_receive_buffer_size()</function> + return an integer greater than, or equal to, + <constant>0</constant>. On failure, a negative error code is + returned.</para> + + <para>On success, <function>udev_monitor_get_fd()</function> + returns the file descriptor used by this monitor. On failure, + a negative error code is returned.</para> + + <para><function>udev_monitor_get_udev()</function> always returns + a pointer to the udev context that this monitor is associated + with.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_monitor_filter_update</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/libudev/udev_new.xml b/src/libudev/udev_new.xml new file mode 100644 index 0000000000..587835a3ca --- /dev/null +++ b/src/libudev/udev_new.xml @@ -0,0 +1,110 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 David Herrmann <dh.herrmann@gmail.com> + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="udev_new" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>udev_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev_new</refname> + <refname>udev_ref</refname> + <refname>udev_unref</refname> + + <refpurpose>Create, acquire and release a udev context object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct udev *<function>udev_new</function></funcdef> + <paramdef><parameter>void</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev *<function>udev_ref</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct udev *<function>udev_unref</function></funcdef> + <paramdef>struct udev *<parameter>udev</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>udev_new()</function> allocates a new udev context + object and returns a pointer to it. This object is opaque and must + not be accessed by the caller via different means than functions + provided by libudev. Initially, the reference count of the context + is 1. You can acquire further references, and drop gained references + via <function>udev_ref()</function> and + <function>udev_unref()</function>. Once the reference count hits 0, + the context object is destroyed and freed.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>udev_new()</function> returns a pointer + to the allocated udev context. On failure, <constant>NULL</constant> + is returned. <function>udev_ref()</function> returns the argument + that it was passed, unmodified. <function>udev_unref()</function> + always returns <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/.gitignore b/src/manpages/.gitignore new file mode 100644 index 0000000000..d928e5a83f --- /dev/null +++ b/src/manpages/.gitignore @@ -0,0 +1,5 @@ +/systemd.directives.xml +/systemd.index.xml +/*.[13578] +/*.html +/custom-entities.ent diff --git a/src/manpages/binfmt.d.xml b/src/manpages/binfmt.d.xml new file mode 100644 index 0000000000..5b63cfb4c3 --- /dev/null +++ b/src/manpages/binfmt.d.xml @@ -0,0 +1,101 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="binfmt.d" conditional='ENABLE_BINFMT' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>binfmt.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>binfmt.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>binfmt.d</refname> + <refpurpose>Configure additional binary formats for + executables at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/binfmt.d/*.conf</filename></para> + <para><filename>/run/binfmt.d/*.conf</filename></para> + <para><filename>/usr/lib/binfmt.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>At boot, + <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories to register + in the kernel additional binary formats for executables.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each file contains a list of binfmt_misc kernel binary + format rules. Consult <ulink + url="https://www.kernel.org/doc/Documentation/binfmt_misc.txt">binfmt_misc.txt</ulink> + for more information on registration of additional binary formats + and how to write rules.</para> + + <para>Empty lines and lines beginning with ; and # are ignored. + Note that this means you may not use ; and # as delimiter in + binary format rules.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/binfmt.d/wine.conf example:</title> + + <programlisting># Start WINE on Windows executables +:DOSWin:M::MZ::/usr/bin/wine:</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/bootup.xml b/src/manpages/bootup.xml new file mode 100644 index 0000000000..986996398c --- /dev/null +++ b/src/manpages/bootup.xml @@ -0,0 +1,305 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="bootup"> + + <refentryinfo> + <title>bootup</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>bootup</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>bootup</refname> + <refpurpose>System bootup process</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A number of different components are involved in the system + boot. Immediately after power-up, the system BIOS will do minimal + hardware initialization, and hand control over to a boot loader + stored on a persistent storage device. This boot loader will then + invoke an OS kernel from disk (or the network). In the Linux case, + this kernel (optionally) extracts and executes an initial RAM disk + image (initrd), such as generated by + <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + which looks for the root file system (possibly using + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for this). After the root file system is found and mounted, the + initrd hands over control to the host's system manager (such as + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + stored on the OS image, which is then responsible for probing all + remaining hardware, mounting all necessary file systems and + spawning all configured services.</para> + + <para>On shutdown, the system manager stops all services, unmounts + all file systems (detaching the storage technologies backing + them), and then (optionally) jumps back into the initrd code which + unmounts/detaches the root file system and the storage it resides + on. As a last step, the system is powered down.</para> + + <para>Additional information about the system boot process may be + found in + <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>System Manager Bootup</title> + + <para>At boot, the system manager on the OS image is responsible + for initializing the required file systems, services and drivers + that are necessary for operation of the system. On + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + systems, this process is split up in various discrete steps which + are exposed as target units. (See + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for detailed information about target units.) The boot-up process + is highly parallelized so that the order in which specific target + units are reached is not deterministic, but still adheres to a + limited amount of ordering structure.</para> + + <para>When systemd starts up the system, it will activate all + units that are dependencies of <filename>default.target</filename> + (as well as recursively all dependencies of these dependencies). + Usually, <filename>default.target</filename> is simply an alias of + <filename>graphical.target</filename> or + <filename>multi-user.target</filename>, depending on whether the + system is configured for a graphical UI or only for a text + console. To enforce minimal ordering between the units pulled in, + a number of well-known target units are available, as listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>The following chart is a structural overview of these + well-known units and their position in the boot-up logic. The + arrows describe which units are pulled in and ordered before which + other units. Units near the top are started before units nearer to + the bottom of the chart.</para> + +<programlisting>local-fs-pre.target + | + v +(various mounts and (various swap (various cryptsetup + fsck services...) devices...) devices...) (various low-level (various low-level + | | | services: udevd, API VFS mounts: + v v v tmpfiles, random mqueue, configfs, + local-fs.target swap.target cryptsetup.target seed, sysctl, ...) debugfs, ...) + | | | | | + \__________________|_________________ | ___________________|____________________/ + \|/ + v + sysinit.target + | + ____________________________________/|\________________________________________ + / | | | \ + | | | | | + v v | v v + (various (various | (various rescue.service + timers...) paths...) | sockets...) | + | | | | v + v v | v <emphasis>rescue.target</emphasis> + timers.target paths.target | sockets.target + | | | | + v \_________________ | ___________________/ + \|/ + v + basic.target + | + ____________________________________/| emergency.service + / | | | + | | | v + v v v <emphasis>emergency.target</emphasis> + display- (various system (various system + manager.service services services) + | required for | + | graphical UIs) v + | | <emphasis>multi-user.target</emphasis> + | | | + \_________________ | _________________/ + \|/ + v + <emphasis>graphical.target</emphasis></programlisting> + + <para>Target units that are commonly used as boot targets are + <emphasis>emphasized</emphasis>. These units are good choices as + goal targets, for example by passing them to the + <varname>systemd.unit=</varname> kernel command line option (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + or by symlinking <filename>default.target</filename> to them. + </para> + + <para><filename>timers.target</filename> is pulled-in by + <filename>basic.target</filename> asynchronously. This allows + timers units to depend on services which become only available + later in boot.</para> + </refsect1> + + <refsect1> + <title>Bootup in the Initial RAM Disk (initrd)</title> + <para>The initial RAM disk implementation (initrd) can be set up + using systemd as well. In this case, boot up inside the initrd + follows the following structure.</para> + + <para>The default target in the initrd is + <filename>initrd.target</filename>. The bootup process begins + identical to the system manager bootup (see above) until it + reaches <filename>basic.target</filename>. From there, systemd + approaches the special target <filename>initrd.target</filename>. + When the root device becomes available, + <filename>initd-root-device.target</filename> is reached. + If the root device can be mounted at + <filename>/sysroot</filename>, the + <filename>sysroot.mount</filename> unit becomes active and + <filename>initrd-root-fs.target</filename> is reached. The service + <filename>initrd-parse-etc.service</filename> scans + <filename>/sysroot/etc/fstab</filename> for a possible + <filename>/usr</filename> mount point and additional entries + marked with the <emphasis>x-initrd.mount</emphasis> option. All + entries found are mounted below <filename>/sysroot</filename>, and + <filename>initrd-fs.target</filename> is reached. The service + <filename>initrd-cleanup.service</filename> isolates to the + <filename>initrd-switch-root.target</filename>, where cleanup + services can run. As the very last step, the + <filename>initrd-switch-root.service</filename> is activated, + which will cause the system to switch its root to + <filename>/sysroot</filename>. + </para> + +<programlisting> : (beginning identical to above) + : + v + basic.target + | emergency.service + ______________________/| | + / | v + | initrd-root-device.target <emphasis>emergency.target</emphasis> + | | + | v + | sysroot.mount + | | + | v + | initrd-root-fs.target + | | + | v + v initrd-parse-etc.service + (custom initrd | + services...) v + | (sysroot-usr.mount and + | various mounts marked + | with fstab option + | x-initrd.mount...) + | | + | v + | initrd-fs.target + \______________________ | + \| + v + initrd.target + | + v + initrd-cleanup.service + isolates to + initrd-switch-root.target + | + v + ______________________/| + / v + | initrd-udevadm-cleanup-db.service + v | + (custom initrd | + services...) | + \______________________ | + \| + v + initrd-switch-root.target + | + v + initrd-switch-root.service + | + v + Transition to Host OS</programlisting> + </refsect1> + + <refsect1> + <title>System Manager Shutdown</title> + + <para>System shutdown with systemd also consists of various target + units with some minimal ordering structure applied:</para> + +<programlisting> (conflicts with (conflicts with + all system all file system + services) mounts, swaps, + | cryptsetup + | devices, ...) + | | + v v + shutdown.target umount.target + | | + \_______ ______/ + \ / + v + (various low-level + services) + | + v + final.target + | + _____________________________________/ \_________________________________ + / | | \ + | | | | + v v v v +systemd-reboot.service systemd-poweroff.service systemd-halt.service systemd-kexec.service + | | | | + v v v v + <emphasis>reboot.target</emphasis> <emphasis>poweroff.target</emphasis> <emphasis>halt.target</emphasis> <emphasis>kexec.target</emphasis></programlisting> + + <para>Commonly used system shutdown targets are + <emphasis>emphasized</emphasis>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/coredump.conf.xml b/src/manpages/coredump.conf.xml new file mode 100644 index 0000000000..4f95680a3a --- /dev/null +++ b/src/manpages/coredump.conf.xml @@ -0,0 +1,161 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="coredump.conf" conditional="ENABLE_COREDUMP" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>coredump.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>coredump.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>coredump.conf</refname> + <refname>coredump.conf.d</refname> + <refpurpose>Core dump storage configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/coredump.conf</filename></para> + <para><filename>/etc/systemd/coredump.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/coredump.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/coredump.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure the behavior of + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used + is determined by the kernel's + <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + setting. See + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> + pages for the details.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Coredump]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>Storage=</varname></term> + + <listitem><para>Controls where to store cores. One of + <literal>none</literal>, <literal>external</literal>, + <literal>journal</literal>, and <literal>both</literal>. When + <literal>none</literal>, the core dumps will be logged but not + stored permanently. When <literal>external</literal> (the + default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>. + When <literal>journal</literal>, cores will be stored in + the journal and rotated following normal journal + rotation patterns. When <literal>both</literal>, cores + will be stored in both locations.</para> + + <para>When cores are stored in the journal, they might be + compressed following journal compression settings, see + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + When cores are stored externally, they will be compressed + by default, see below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Compress=</varname></term> + + <listitem><para>Controls compression for external + storage. Takes a boolean argument, which defaults to + <literal>yes</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProcessSizeMax=</varname></term> + + <listitem><para>The maximum size in bytes of a core + which will be processed. Core dumps exceeding this size + will be logged, but the backtrace will not be generated + and the core will not be stored.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExternalSizeMax=</varname></term> + <term><varname>JournalSizeMax=</varname></term> + + <listitem><para>The maximum (uncompressed) size in bytes of a + core to be saved.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxUse=</varname></term> + <term><varname>KeepFree=</varname></term> + + <listitem><para>Enforce limits on the disk space taken up by + externally stored core dumps. <option>MaxUse=</option> makes + sure that old core dumps are removed as soon as the total disk + space taken up by core dumps grows beyond this limit (defaults + to 10% of the total disk size). <option>KeepFree=</option> + controls how much disk space to keep free at least (defaults + to 15% of the total disk size). Note that the disk space used + by core dumps might temporarily exceed these limits while + core dumps are processed. Note that old core dumps are also + removed based on time via + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set + either value to 0 to turn off size-based + clean-up.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/crypttab.xml b/src/manpages/crypttab.xml new file mode 100644 index 0000000000..1de834a045 --- /dev/null +++ b/src/manpages/crypttab.xml @@ -0,0 +1,416 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. + + This is based on crypttab(5) from Fedora's initscripts package, which in + turn is based on Debian's version. + + The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>. + +--> +<refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP'> + + <refentryinfo> + <title>crypttab</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Miloslav</firstname> + <surname>Trmac</surname> + <email>mitr@redhat.com</email> + </author> + <author> + <contrib>Documentation</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>crypttab</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>crypttab</refname> + <refpurpose>Configuration for encrypted block devices</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/crypttab</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/crypttab</filename> file describes + encrypted block devices that are set up during system boot.</para> + + <para>Empty lines and lines starting with the <literal>#</literal> + character are ignored. Each of the remaining lines describes one + encrypted block device, fields on the line are delimited by white + space. The first two fields are mandatory, the remaining two are + optional.</para> + + <para>Setting up encrypted block devices using this file supports + three encryption modes: LUKS, TrueCrypt and plain. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information about each mode. When no mode is specified in + the options field and the block device contains a LUKS signature, + it is opened as a LUKS device; otherwise, it is assumed to be in + raw dm-crypt (plain mode) format.</para> + + <para>The first field contains the name of the resulting encrypted + block device; the device is set up within + <filename>/dev/mapper/</filename>.</para> + + <para>The second field contains a path to the underlying block + device or file, or a specification of a block device via + <literal>UUID=</literal> followed by the UUID.</para> + + <para>The third field specifies the encryption password. If the + field is not present or the password is set to + <literal>none</literal> or <literal>-</literal>, the password has + to be manually entered during system boot. Otherwise, the field is + interpreted as a absolute path to a file containing the encryption + password. For swap encryption, <filename>/dev/urandom</filename> + or the hardware device <filename>/dev/hw_random</filename> can be + used as the password file; using <filename>/dev/random</filename> + may prevent boot completion if the system does not have enough + entropy to generate a truly random encryption key.</para> + + <para>The fourth field, if present, is a comma-delimited list of + options. The following options are recognized:</para> + + <variablelist class='fstab-options'> + + <varlistentry> + <term><option>discard</option></term> + + <listitem><para>Allow discard requests to be passed through + the encrypted block device. This improves performance on SSD + storage but has security implications.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>cipher=</option></term> + + <listitem><para>Specifies the cipher to use. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this option. A + cipher with unpredictable IV values, such as + <literal>aes-cbc-essiv:sha256</literal>, is + recommended.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>hash=</option></term> + + <listitem><para>Specifies the hash to use for password + hashing. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>header=</option></term> + + <listitem><para>Use a detached (separated) metadata device or + file where the LUKS header is stored. This option is only + relevant for LUKS devices. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>offset=</option></term> + + <listitem><para>Start offset in the backend device, in 512-byte sectors. + This option is only relevant for plain devices. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>skip=</option></term> + + <listitem><para>How many 512-byte sectors of the encrypted data to skip + at the beginning. This is different from the <option>--offset</option> + option with respect to the sector numbers used in initialization vector + (IV) calculation. Using <option>--offset</option> will shift the IV + calculation by the same negative amount. Hence, if <option>--offset n</option> is given, + sector n will get a sector number of 0 for the IV calculation. + Using <option>--skip</option> causes sector n to also be the first + sector of the mapped device, but with its number for IV generation being n.</para> + + <para>This option is only relevant for plain devices.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>keyfile-offset=</option></term> + + <listitem><para>Specifies the number of bytes to skip at the + start of the key file. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>keyfile-size=</option></term> + + <listitem><para>Specifies the maximum number of bytes to read + from the key file. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this option. This + option is ignored in plain encryption mode, as the key file + size is then given by the key size.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>key-slot=</option></term> + + <listitem><para>Specifies the key slot to compare the + passphrase or key against. If the key slot does not match the + given passphrase or key, but another would, the setup of the + device will fail regardless. This option implies + <option>luks</option>. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values. The default is to try all key slots in + sequential order.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>luks</option></term> + + <listitem><para>Force LUKS mode. When this mode is used, the + following options are ignored since they are provided by the + LUKS header on the device: <option>cipher=</option>, + <option>hash=</option>, + <option>size=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>noauto</option></term> + + <listitem><para>This device will not be automatically unlocked + on boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>The system will not wait for the device to + show up and be unlocked at boot, and not fail the boot if it + does not show up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>plain</option></term> + + <listitem><para>Force plain encryption mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>read-only</option></term><term><option>readonly</option></term> + + <listitem><para>Set up the encrypted block device in read-only + mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>size=</option></term> + + <listitem><para>Specifies the key size in bits. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>swap</option></term> + + <listitem><para>The encrypted block device will be used as a + swap device, and will be formatted accordingly after setting + up the encrypted block device, with + <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <option>plain</option>.</para> + + <para>WARNING: Using the <option>swap</option> option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt</option></term> + + <listitem><para>Use TrueCrypt encryption mode. When this mode + is used, the following options are ignored since they are + provided by the TrueCrypt header on the device or do not + apply: + <option>cipher=</option>, + <option>hash=</option>, + <option>keyfile-offset=</option>, + <option>keyfile-size=</option>, + <option>size=</option>.</para> + + <para>When this mode is used, the passphrase is read from the + key file given in the third field. Only the first line of this + file is read, excluding the new line character.</para> + + <para>Note that the TrueCrypt format uses both passphrase and + key files to derive a password for the volume. Therefore, the + passphrase and all key files need to be provided. Use + <option>tcrypt-keyfile=</option> to provide the absolute path + to all key files. When using an empty passphrase in + combination with one or more key files, use + <literal>/dev/null</literal> as the password file in the third + field.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-hidden</option></term> + + <listitem><para>Use the hidden TrueCrypt volume. This option + implies <option>tcrypt</option>.</para> + + <para>This will map the hidden volume that is inside of the + volume provided in the second field. Please note that there is + no protection for the hidden volume if the outer volume is + mounted instead. See + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information on this limitation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-keyfile=</option></term> + + <listitem><para>Specifies the absolute path to a key file to + use for a TrueCrypt volume. This implies + <option>tcrypt</option> and can be used more than once to + provide several key files.</para> + + <para>See the entry for <option>tcrypt</option> on the + behavior of the passphrase and key files when using TrueCrypt + encryption mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-system</option></term> + + <listitem><para>Use TrueCrypt in system encryption mode. This + option implies <option>tcrypt</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>timeout=</option></term> + + <listitem><para>Specifies the timeout for querying for a + password. If no unit is specified, seconds is used. Supported + units are s, ms, us, min, h, d. A timeout of 0 waits + indefinitely (which is the default).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.device-timeout=</option></term> + + <listitem><para>Specifies how long systemd should wait for a + device to show up before giving up on the entry. The argument + is a time in seconds or explicitly specified units of + <literal>s</literal>, + <literal>min</literal>, + <literal>h</literal>, + <literal>ms</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tmp</option></term> + + <listitem><para>The encrypted block device will be prepared + for using it as <filename>/tmp</filename>; it will be + formatted using + <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <option>plain</option>.</para> + + <para>WARNING: Using the <option>tmp</option> option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tries=</option></term> + + <listitem><para>Specifies the maximum number of times the user + is queried for a password. The default is 3. If set to 0, the + user is queried for a password indefinitely.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>verify</option></term> + + <listitem><para> If the encryption password is read from + console, it has to be entered twice to prevent + typos.</para></listitem> + </varlistentry> + + </variablelist> + + <para>At early boot and when the system manager configuration is + reloaded, this file is translated into native systemd units by + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/crypttab example</title> + <para>Set up four encrypted block devices. One using LUKS for + normal storage, another one for usage as a swap device and two + TrueCrypt volumes.</para> + + <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b +swap /dev/sda7 /dev/urandom swap +truecrypt /dev/sda2 /etc/container_password tcrypt +hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/custom-html.xsl b/src/manpages/custom-html.xsl new file mode 100644 index 0000000000..e89d73e7f1 --- /dev/null +++ b/src/manpages/custom-html.xsl @@ -0,0 +1,299 @@ +<?xml version='1.0'?> <!--*-nxml-*--> + +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> +<!-- + - The docbook stylesheet injects empty anchor tags into generated HTML, identified by an auto-generated ID. + - Ask the docbook stylesheet to generate reproducible output when generating (these) ID values. + - This makes the output of this stylesheet reproducible across identical invocations on the same input, + - which is an easy and significant win for achieving reproducible builds. + - + - It may be even better to strip the empty anchors from the document output in addition to turning on consistent IDs, + - for this stylesheet contains its own custom ID logic (for generating permalinks) already. + --> +<xsl:param name="generate.consistent.ids" select="1"/> + +<!-- translate man page references to links to html pages --> +<xsl:template match="citerefentry[not(@project)]"> + <a> + <xsl:attribute name="href"> + <xsl:value-of select="refentrytitle"/><xsl:text>.html#</xsl:text> + <xsl:value-of select="refentrytitle/@target"/> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='man-pages'] | citerefentry[manvolnum='2'] | citerefentry[manvolnum='4']"> + <a> + <xsl:attribute name="href"> + <xsl:text>http://man7.org/linux/man-pages/man</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>/</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>.</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>.html</xsl:text> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='die-net']"> + <a> + <xsl:attribute name="href"> + <xsl:text>http://linux.die.net/man/</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>/</xsl:text> + <xsl:value-of select="refentrytitle"/> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='mankier']"> + <a> + <xsl:attribute name="href"> + <xsl:text>https://www.mankier.com/</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>/</xsl:text> + <xsl:value-of select="refentrytitle"/> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='archlinux']"> + <a> + <xsl:attribute name="href"> + <xsl:text>https://www.archlinux.org/</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>/</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>.</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>.html</xsl:text> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='freebsd']"> + <a> + <xsl:attribute name="href"> + <xsl:text>https://www.freebsd.org/cgi/man.cgi?</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>(</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>)</xsl:text> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<xsl:template match="citerefentry[@project='dbus']"> + <a> + <xsl:attribute name="href"> + <xsl:text>http://dbus.freedesktop.org/doc/</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>.</xsl:text> + <xsl:value-of select="manvolnum"/> + <xsl:text>.html</xsl:text> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<!-- + - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template + - this conflict resolution is necessary to prevent malformed HTML output (multiple ID attributes with the same value) + - and it fixes xsltproc warnings during compilation of HTML man pages + - + - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output. + - It uses two parameters: + templateID the proposed ID string to use which must be checked for conflicts + keyNode the context node which 'produced' the given templateID. + - + - Conflicts are detected solely based on keyNode, templateID is not taken into account for that purpose. + --> +<xsl:template name="generateID"> + <!-- node which generatedID needs to assume as the 'source' of the ID --> + <xsl:param name="keyNode"/> + <!-- suggested value for generatedID output, a contextually meaningful ID string --> + <xsl:param name="templateID"/> + <xsl:variable name="conflictSource" select="preceding::refsect1/title|preceding::refsect1/info/title| + preceding::refsect2/title|preceding::refsect2/info/title| + preceding::varlistentry/term[1]"/> + <xsl:variable name="conflictCount" select="count($conflictSource[. = $keyNode])"/> + <xsl:choose> + <!-- special case conflictCount = 0 to preserve compatibility with URLs generated by previous versions of this XSL stylesheet where possible --> + <xsl:when test="$conflictCount = 0"> + <xsl:value-of select="$templateID"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($templateID, $conflictCount)"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- + - a helper template to abstract over the structure of generated subheading + permalink HTML output + - It helps reduce tedious repetition and groups all actual markup output (as opposed to URL/ID logic) in a single location. + --> +<xsl:template name="permalink"> + <xsl:param name="nodeType"/> <!-- local name of the element node to generate, e.g. 'h2' for <h2></h2> --> + <xsl:param name="nodeContent"/> <!-- nodeset to apply further templates to obtain the content of the subheading/term --> + <xsl:param name="linkTitle"/> <!-- value for title attribute of generated permalink, e.g. 'this is a permalink' --> + + <!-- parameters passed to generateID template, otherwise unused. --> + <xsl:param name="keyNode"/> + <xsl:param name="templateID"/> + + <!-- + - If stable URLs with fragment markers (references to the ID) turn out not to be important: + - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely. + - Alternatively, if xsltproc is patched to generate reproducible generate-id() output, the same simplifications can be + - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet. + --> + <xsl:variable name="generatedID"> + <xsl:call-template name="generateID"> + <xsl:with-param name="keyNode" select="$keyNode"/> + <xsl:with-param name="templateID" select="$templateID"/> + </xsl:call-template> + </xsl:variable> + + <xsl:element name="{$nodeType}"> + <xsl:attribute name="id"> + <xsl:value-of select="$generatedID"/> + </xsl:attribute> + <xsl:apply-templates select="$nodeContent"/> + <a class="headerlink" title="{$linkTitle}" href="#{$generatedID}">¶</a> + </xsl:element> +</xsl:template> + +<!-- simple wrapper around permalink to avoid repeating common info for each level of subheading covered by the permalink logic (h2, h3) --> +<xsl:template name="headerlink"> + <xsl:param name="nodeType"/> + <xsl:call-template name="permalink"> + <xsl:with-param name="nodeType" select="$nodeType"/> + <xsl:with-param name="linkTitle" select="'Permalink to this headline'"/> + <xsl:with-param name="nodeContent" select="node()"/> + <xsl:with-param name="keyNode" select="."/> + <!-- + - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called. + - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text). + - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it. + --> + <xsl:with-param name="templateID"> + <xsl:call-template name="inline.charseq"/> + </xsl:with-param> + </xsl:call-template> +</xsl:template> + +<xsl:template match="refsect1/title|refsect1/info/title"> + <!-- the ID is output in the block.object call for refsect1 --> + <xsl:call-template name="headerlink"> + <xsl:with-param name="nodeType" select="'h2'"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="refsect2/title|refsect2/info/title"> + <xsl:call-template name="headerlink"> + <xsl:with-param name="nodeType" select="'h3'"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="varlistentry"> + <xsl:call-template name="permalink"> + <xsl:with-param name="nodeType" select="'dt'"/> + <xsl:with-param name="linkTitle" select="'Permalink to this term'"/> + <xsl:with-param name="nodeContent" select="term"/> + <xsl:with-param name="keyNode" select="term[1]"/> + <!-- + - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called. + - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text). + - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it. + --> + <xsl:with-param name="templateID"> + <xsl:call-template name="inline.charseq"> + <xsl:with-param name="content" select="term[1]"/> + </xsl:call-template> + </xsl:with-param> + </xsl:call-template> + <dd> + <xsl:apply-templates select="listitem"/> + </dd> +</xsl:template> + + +<!-- add Index link at top of page --> +<xsl:template name="user.header.content"> + <style> + a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; + } + + a.headerlink:hover { + background-color: #c60f0f; + color: white; + } + + h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink { + visibility: visible; + } + </style> + + <a> + <xsl:attribute name="href"> + <xsl:text>index.html</xsl:text> + </xsl:attribute> + <xsl:text>Index </xsl:text> + </a>· + <a> + <xsl:attribute name="href"> + <xsl:text>systemd.directives.html</xsl:text> + </xsl:attribute> + <xsl:text>Directives </xsl:text> + </a> + + <span style="float:right"> + <xsl:text>systemd </xsl:text> + <xsl:value-of select="$systemd.version"/> + </span> + <hr/> +</xsl:template> + +<xsl:template match="literal"> + <xsl:text>"</xsl:text> + <xsl:call-template name="inline.monoseq"/> + <xsl:text>"</xsl:text> +</xsl:template> + +<!-- Switch things to UTF-8, ISO-8859-1 is soo yesteryear --> +<xsl:output method="html" encoding="UTF-8" indent="no"/> + +</xsl:stylesheet> diff --git a/src/manpages/custom-man.xsl b/src/manpages/custom-man.xsl new file mode 100644 index 0000000000..e1b8d3618a --- /dev/null +++ b/src/manpages/custom-man.xsl @@ -0,0 +1,64 @@ +<?xml version='1.0'?> <!--*-nxml-*--> + +<!-- + This file is part of systemd. + + Copyright 2013 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + extension-element-prefixes="exsl" + version="1.0"> + +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/> + +<xsl:template name="top.comment" /> + +<xsl:template name="TH.title.line"> + <xsl:param name="title"/> + <xsl:param name="section"/> + <xsl:param name="extra1"/> + <xsl:param name="extra2"/> + <xsl:param name="extra3"/> + + <xsl:call-template name="mark.subheading"/> + <xsl:text>.TH "</xsl:text> + <xsl:call-template name="string.upper"> + <xsl:with-param name="string"> + <xsl:value-of select="normalize-space($title)"/> + </xsl:with-param> + </xsl:call-template> + <xsl:text>" "</xsl:text> + <xsl:value-of select="normalize-space($section)"/> + <xsl:text>" "" "systemd </xsl:text> + <xsl:value-of select="$systemd.version"/> + <xsl:text>" "</xsl:text> + <xsl:value-of select="normalize-space($extra3)"/> + <xsl:text>" </xsl:text> + <xsl:call-template name="mark.subheading"/> +</xsl:template> + +<xsl:template match="literal"> + <xsl:if test="$man.hyphenate.computer.inlines = 0"> + <xsl:call-template name="suppress.hyphenation"/> + </xsl:if> + <xsl:text>"</xsl:text> + <xsl:call-template name="inline.monoseq"/> + <xsl:text>"</xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/src/manpages/daemon.xml b/src/manpages/daemon.xml new file mode 100644 index 0000000000..a649749683 --- /dev/null +++ b/src/manpages/daemon.xml @@ -0,0 +1,763 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="daemon"> + + <refentryinfo> + <title>daemon</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>daemon</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>daemon</refname> + <refpurpose>Writing and packaging system daemons</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A daemon is a service process that runs in the background + and supervises the system or provides functionality to other + processes. Traditionally, daemons are implemented following a + scheme originating in SysV Unix. Modern daemons should follow a + simpler yet more powerful scheme (here called "new-style" + daemons), as implemented by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This manual page covers both schemes, and in particular includes + recommendations for daemons that shall be included in the systemd + init system.</para> + + <refsect2> + <title>SysV Daemons</title> + + <para>When a traditional SysV daemon starts, it should execute + the following steps as part of the initialization. Note that + these steps are unnecessary for new-style daemons (see below), + and should only be implemented if compatibility with SysV is + essential.</para> + + <orderedlist> + <listitem><para>Close all open file descriptors except + standard input, output, and error (i.e. the first three file + descriptors 0, 1, 2). This ensures that no accidentally passed + file descriptor stays around in the daemon process. On Linux, + this is best implemented by iterating through + <filename>/proc/self/fd</filename>, with a fallback of + iterating from file descriptor 3 to the value returned by + <function>getrlimit()</function> for + <constant>RLIMIT_NOFILE</constant>. </para></listitem> + + <listitem><para>Reset all signal handlers to their default. + This is best done by iterating through the available signals + up to the limit of <constant>_NSIG</constant> and resetting + them to <constant>SIG_DFL</constant>.</para></listitem> + + <listitem><para>Reset the signal mask + using + <function>sigprocmask()</function>.</para></listitem> + + <listitem><para>Sanitize the environment block, removing or + resetting environment variables that might negatively impact + daemon runtime.</para></listitem> + + <listitem><para>Call <function>fork()</function>, to create a + background process.</para></listitem> + + <listitem><para>In the child, call + <function>setsid()</function> to detach from any terminal and + create an independent session.</para></listitem> + + <listitem><para>In the child, call <function>fork()</function> + again, to ensure that the daemon can never re-acquire a + terminal again.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the first + child, so that only the second child (the actual daemon + process) stays around. This ensures that the daemon process is + re-parented to init/PID 1, as all daemons should + be.</para></listitem> + + <listitem><para>In the daemon process, connect + <filename>/dev/null</filename> to standard input, output, and + error.</para></listitem> + + <listitem><para>In the daemon process, reset the umask to 0, + so that the file modes passed to <function>open()</function>, + <function>mkdir()</function> and suchlike directly control the + access mode of the created files and + directories.</para></listitem> + + <listitem><para>In the daemon process, change the current + directory to the root directory (/), in order to avoid that + the daemon involuntarily blocks mount points from being + unmounted.</para></listitem> + + <listitem><para>In the daemon process, write the daemon PID + (as returned by <function>getpid()</function>) to a PID file, + for example <filename>/run/foobar.pid</filename> (for a + hypothetical daemon "foobar") to ensure that the daemon cannot + be started more than once. This must be implemented in + race-free fashion so that the PID file is only updated when it + is verified at the same time that the PID previously stored in + the PID file no longer exists or belongs to a foreign + process.</para></listitem> + + <listitem><para>In the daemon process, drop privileges, if + possible and applicable.</para></listitem> + + <listitem><para>From the daemon process, notify the original + process started that initialization is complete. This can be + implemented via an unnamed pipe or similar communication + channel that is created before the first + <function>fork()</function> and hence available in both the + original and the daemon process.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the + original process. The process that invoked the daemon must be + able to rely on that this <function>exit()</function> happens + after initialization is complete and all external + communication channels are established and + accessible.</para></listitem> + </orderedlist> + + <para>The BSD <function>daemon()</function> function should not + be used, as it implements only a subset of these steps.</para> + + <para>A daemon that needs to provide compatibility with SysV + systems should implement the scheme pointed out above. However, + it is recommended to make this behavior optional and + configurable via a command line argument to ease debugging as + well as to simplify integration into systems using + systemd.</para> + </refsect2> + + <refsect2> + <title>New-Style Daemons</title> + + <para>Modern services for GNU/Linux should be implemented as + new-style daemons. This makes it easier to supervise and control + them at runtime and simplifies their implementation.</para> + + <para>For developing a new-style daemon, none of the + initialization steps recommended for SysV daemons need to be + implemented. New-style init systems such as systemd make all of + them redundant. Moreover, since some of these steps interfere + with process monitoring, file descriptor passing and other + functionality of the init system, it is recommended not to + execute them when run as new-style service.</para> + + <para>Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is + guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons will be executed in their own session, with standard input + connected to <filename>/dev/null</filename> and standard output/error connected to the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + logging service, unless otherwise configured. The umask is reset. + </para> + + <para>It is recommended for new-style daemons to implement the + following:</para> + + <orderedlist> + <listitem><para>If <constant>SIGTERM</constant> is received, + shut down the daemon and exit cleanly.</para></listitem> + + <listitem><para>If <constant>SIGHUP</constant> is received, + reload the configuration files, if this + applies.</para></listitem> + + <listitem><para>Provide a correct exit code from the main + daemon process, as this is used by the init system to detect + service errors and problems. It is recommended to follow the + exit code scheme as defined in the <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + recommendations for SysV init + scripts</ulink>.</para></listitem> + + <listitem><para>If possible and applicable, expose the + daemon's control interface via the D-Bus IPC system and grab a + bus name as last step of initialization.</para></listitem> + + <listitem><para>For integration in systemd, provide a + <filename>.service</filename> unit file that carries + information about starting, stopping and otherwise maintaining + the daemon. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>As much as possible, rely on the init system's + functionality to limit the access of the daemon to files, + services and other resources, i.e. in the case of systemd, + rely on systemd's resource limit control instead of + implementing your own, rely on systemd's privilege dropping + code instead of implementing it in the daemon, and similar. + See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the available controls.</para></listitem> + + <listitem><para>If D-Bus is used, make your daemon + bus-activatable by supplying a D-Bus service activation + configuration file. This has multiple advantages: your daemon + may be started lazily on-demand; it may be started in parallel + to other daemons requiring it — which maximizes + parallelization and boot-up speed; your daemon can be + restarted on failure without losing any bus requests, as the + bus queues requests for activatable services. See below for + details.</para></listitem> + + <listitem><para>If your daemon provides services to other + local processes or remote clients via a socket, it should be + made socket-activatable following the scheme pointed out + below. Like D-Bus activation, this enables on-demand starting + of services as well as it allows improved parallelization of + service start-up. Also, for state-less protocols (such as + syslog, DNS), a daemon implementing socket-based activation + can be restarted without losing a single request. See below + for details.</para></listitem> + + <listitem><para>If applicable, a daemon should notify the init + system about startup completion or status updates via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + interface.</para></listitem> + + <listitem><para>Instead of using the + <function>syslog()</function> call to log directly to the + system syslog service, a new-style daemon may choose to simply + log to standard error via <function>fprintf()</function>, + which is then forwarded to syslog by the init system. If log + levels are necessary, these can be encoded by prefixing + individual log lines with strings like + <literal><4></literal> (for log level 4 "WARNING" in the + syslog priority scheme), following a similar style as the + Linux kernel's <function>printk()</function> level system. For + details, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>These recommendations are similar but not identical to the + <ulink + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple + MacOS X Daemon Requirements</ulink>.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Activation</title> + + <para>New-style init systems provide multiple additional + mechanisms to activate services, as detailed below. It is common + that services are configured to be activated via more than one + mechanism at the same time. An example for systemd: + <filename>bluetoothd.service</filename> might get activated either + when Bluetooth hardware is plugged in, or when an application + accesses its programming interfaces via D-Bus. Or, a print server + daemon might get activated when traffic arrives at an IPP port, or + when a printer is plugged in, or when a file is queued in the + printer spool directory. Even for services that are intended to be + started on system bootup unconditionally, it is a good idea to + implement some of the various activation schemes outlined below, + in order to maximize parallelization. If a daemon implements a + D-Bus service or listening socket, implementing the full bus and + socket activation scheme allows starting of the daemon with its + clients in parallel (which speeds up boot-up), since all its + communication channels are established already, and no request is + lost because client requests will be queued by the bus system (in + case of D-Bus) or the kernel (in case of sockets) until the + activation is completed.</para> + + <refsect2> + <title>Activation on Boot</title> + + <para>Old-style daemons are usually activated exclusively on + boot (and manually by the administrator) via SysV init scripts, + as detailed in the <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + Linux Standard Base Core Specification</ulink>. This method of + activation is supported ubiquitously on GNU/Linux init systems, both + old-style and new-style systems. Among other issues, SysV init + scripts have the disadvantage of involving shell scripts in the + boot process. New-style init systems generally employ updated + versions of activation, both during boot-up and during runtime + and using more minimal service description files.</para> + + <para>In systemd, if the developer or administrator wants to + make sure that a service or other unit is activated + automatically on boot, it is recommended to place a symlink to + the unit file in the <filename>.wants/</filename> directory of + either <filename>multi-user.target</filename> or + <filename>graphical.target</filename>, which are normally used + as boot targets at system startup. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about the <filename>.wants/</filename> directories, + and + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about the two boot targets.</para> + + </refsect2> + + <refsect2> + <title>Socket-Based Activation</title> + + <para>In order to maximize the possible parallelization and + robustness and simplify configuration and development, it is + recommended for all new-style daemons that communicate via + listening sockets to employ socket-based activation. In a + socket-based activation scheme, the creation and binding of the + listening socket as primary communication channel of daemons to + local (and sometimes remote) clients is moved out of the daemon + code and into the init system. Based on per-daemon + configuration, the init system installs the sockets and then + hands them off to the spawned process as soon as the respective + daemon is to be started. Optionally, activation of the service + can be delayed until the first inbound traffic arrives at the + socket to implement on-demand activation of daemons. However, + the primary advantage of this scheme is that all providers and + all consumers of the sockets can be started in parallel as soon + as all sockets are established. In addition to that, daemons can + be restarted with losing only a minimal number of client + transactions, or even any client request at all (the latter is + particularly true for state-less protocols, such as DNS or + syslog), because the socket stays bound and accessible during + the restart, and all requests are queued while the daemon cannot + process them.</para> + + <para>New-style daemons which support socket activation must be + able to receive their sockets from the init system instead of + creating and binding them themselves. For details about the + programming interfaces for this scheme provided by systemd, see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + For details about porting existing daemons to socket-based + activation, see below. With minimal effort, it is possible to + implement socket-based activation in addition to traditional + internal socket creation in the same codebase in order to + support both new-style and old-style init systems from the same + daemon binary.</para> + + <para>systemd implements socket-based activation via + <filename>.socket</filename> units, which are described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + When configuring socket units for socket-based activation, it is + essential that all listening sockets are pulled in by the + special target unit <filename>sockets.target</filename>. It is + recommended to place a + <varname>WantedBy=sockets.target</varname> directive in the + <literal>[Install]</literal> section to automatically add such a + dependency on installation of a socket unit. Unless + <varname>DefaultDependencies=no</varname> is set, the necessary + ordering dependencies are implicitly created for all socket + units. For more information about + <filename>sockets.target</filename>, see + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + It is not necessary or recommended to place any additional + dependencies on socket units (for example from + <filename>multi-user.target</filename> or suchlike) when one is + installed in <filename>sockets.target</filename>.</para> + </refsect2> + + <refsect2> + <title>Bus-Based Activation</title> + + <para>When the D-Bus IPC system is used for communication with + clients, new-style daemons should employ bus activation so that + they are automatically activated when a client application + accesses their IPC interfaces. This is configured in D-Bus + service files (not to be confused with systemd service unit + files!). To ensure that D-Bus uses systemd to start-up and + maintain the daemon, use the <varname>SystemdService=</varname> + directive in these service files to configure the matching + systemd service for a D-Bus service. e.g.: For a D-Bus service + whose D-Bus activation file is named + <filename>org.freedesktop.RealtimeKit.service</filename>, make + sure to set + <varname>SystemdService=rtkit-daemon.service</varname> in that + file to bind it to the systemd service + <filename>rtkit-daemon.service</filename>. This is needed to + make sure that the daemon is started in a race-free fashion when + activated via multiple mechanisms simultaneously.</para> + </refsect2> + + <refsect2> + <title>Device-Based Activation</title> + + <para>Often, daemons that manage a particular type of hardware + should be activated only when the hardware of the respective + kind is plugged in or otherwise becomes available. In a + new-style init system, it is possible to bind activation to + hardware plug/unplug events. In systemd, kernel devices + appearing in the sysfs/udev device tree can be exposed as units + if they are tagged with the string <literal>systemd</literal>. + Like any other kind of unit, they may then pull in other units + when activated (i.e. plugged in) and thus implement device-based + activation. systemd dependencies may be encoded in the udev + database via the <varname>SYSTEMD_WANTS=</varname> property. See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Often, it is nicer to pull in services from devices + only indirectly via dedicated targets. Example: Instead of + pulling in <filename>bluetoothd.service</filename> from all the + various bluetooth dongles and other hardware available, pull in + bluetooth.target from them and + <filename>bluetoothd.service</filename> from that target. This + provides for nicer abstraction and gives administrators the + option to enable <filename>bluetoothd.service</filename> via + controlling a <filename>bluetooth.target.wants/</filename> + symlink uniformly with a command like <command>enable</command> + of + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of manipulating the udev ruleset.</para> + </refsect2> + + <refsect2> + <title>Path-Based Activation</title> + + <para>Often, runtime of daemons processing spool files or + directories (such as a printing system) can be delayed until + these file system objects change state, or become non-empty. + New-style init systems provide a way to bind service activation + to file system changes. systemd implements this scheme via + path-based activation configured in <filename>.path</filename> + units, as outlined in + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Timer-Based Activation</title> + + <para>Some daemons that implement clean-up jobs that are + intended to be executed in regular intervals benefit from + timer-based activation. In systemd, this is implemented via + <filename>.timer</filename> units, as described in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Other Forms of Activation</title> + + <para>Other forms of activation have been suggested and + implemented in some systems. However, there are often simpler or + better alternatives, or they can be put together of combinations + of the schemes above. Example: Sometimes, it appears useful to + start daemons or <filename>.socket</filename> units when a + specific IP address is configured on a network interface, + because network sockets shall be bound to the address. However, + an alternative to implement this is by utilizing the Linux + <constant>IP_FREEBIND</constant> socket option, as accessible + via <varname>FreeBind=yes</varname> in systemd socket files (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). This option, when enabled, allows sockets to be + bound to a non-local, not configured IP address, and hence + allows bindings to a particular IP address before it actually + becomes available, making such an explicit dependency to the + configured address redundant. Another often suggested trigger + for service activation is low system load. However, here too, a + more convincing approach might be to make proper use of features + of the operating system, in particular, the CPU or I/O scheduler + of Linux. Instead of scheduling jobs from userspace based on + monitoring the OS scheduler, it is advisable to leave the + scheduling of processes to the OS scheduler itself. systemd + provides fine-grained access to the CPU and I/O schedulers. If a + process executed by the init system shall not negatively impact + the amount of CPU or I/O bandwidth available to other processes, + it should be configured with + <varname>CPUSchedulingPolicy=idle</varname> and/or + <varname>IOSchedulingClass=idle</varname>. Optionally, this may + be combined with timer-based activation to schedule background + jobs during runtime and with minimal impact on the system, and + remove it from the boot phase itself.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Integration with Systemd</title> + + <refsect2> + <title>Writing Systemd Unit Files</title> + + <para>When writing systemd unit files, it is recommended to + consider the following suggestions:</para> + + <orderedlist> + <listitem><para>If possible, do not use the + <varname>Type=forking</varname> setting in service files. But + if you do, make sure to set the PID file path using + <varname>PIDFile=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>If your daemon registers a D-Bus name on the + bus, make sure to use <varname>Type=dbus</varname> in the + service file if possible.</para></listitem> + + <listitem><para>Make sure to set a good human-readable + description string with + <varname>Description=</varname>.</para></listitem> + + <listitem><para>Do not disable + <varname>DefaultDependencies=</varname>, unless you really + know what you do and your unit is involved in early boot or + late system shutdown.</para></listitem> + + <listitem><para>Normally, little if any dependencies should + need to be defined explicitly. However, if you do configure + explicit dependencies, only refer to unit names listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + or names introduced by your own package to keep the unit file + operating system-independent.</para></listitem> + + <listitem><para>Make sure to include an + <literal>[Install]</literal> section including installation + information for the unit file. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. To activate your service on boot, make sure to + add a <varname>WantedBy=multi-user.target</varname> or + <varname>WantedBy=graphical.target</varname> directive. To + activate your socket on boot, make sure to add + <varname>WantedBy=sockets.target</varname>. Usually, you also + want to make sure that when your service is installed, your + socket is installed too, hence add + <varname>Also=foo.socket</varname> in your service file + <filename>foo.service</filename>, for a hypothetical program + <filename>foo</filename>.</para></listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Installing Systemd Service Files</title> + + <para>At the build installation time (e.g. <command>make + install</command> during package build), packages are + recommended to install their systemd unit files in the directory + returned by <command>pkg-config systemd + --variable=systemdsystemunitdir</command> (for system services) + or <command>pkg-config systemd + --variable=systemduserunitdir</command> (for user services). + This will make the services available in the system on explicit + request but not activate them automatically during boot. + Optionally, during package installation (e.g. <command>rpm + -i</command> by the administrator), symlinks should be created + in the systemd configuration directories via the + <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool to activate them automatically on boot.</para> + + <para>Packages using + <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration:</para> + + <programlisting>PKG_PROG_PKG_CONFIG +AC_ARG_WITH([systemdsystemunitdir], + [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],, + [with_systemdsystemunitdir=auto]) +AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [ + def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd) + + AS_IF([test "x$def_systemdsystemunitdir" = "x"], + [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], + [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) + with_systemdsystemunitdir=no], + [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) +AS_IF([test "x$with_systemdsystemunitdir" != "xno"], + [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])]) +AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting> + + <para>This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + user unit directory is left as an exercise for the + reader.)</para> + + <para>Additionally, to ensure that + <command>make distcheck</command> continues to + work, it is recommended to add the following + to the top-level <filename>Makefile.am</filename> + file in + <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based + projects:</para> + + <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> + + <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> + + <programlisting>if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif</programlisting> + + <para>In the + <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <filename>.spec</filename> file, use snippets like the following + to enable/disable the service during + installation/deinstallation. This makes use of the RPM macros + shipped along systemd. Consult the packaging guidelines of your + distribution for details and the equivalent for other package + managers.</para> + + <para>At the top of the file:</para> + + <programlisting>BuildRequires: systemd +%{?systemd_requires}</programlisting> + + <para>And as scriptlets, further down:</para> + + <programlisting>%post +%systemd_post foobar.service foobar.socket + +%preun +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun</programlisting> + + <para>If the service shall be restarted during upgrades, replace + the <literal>%postun</literal> scriptlet above with the + following:</para> + + <programlisting>%postun +%systemd_postun_with_restart foobar.service</programlisting> + + <para>Note that <literal>%systemd_post</literal> and + <literal>%systemd_preun</literal> expect the names of all units + that are installed/removed as arguments, separated by spaces. + <literal>%systemd_postun</literal> expects no arguments. + <literal>%systemd_postun_with_restart</literal> expects the + units to restart as arguments.</para> + + <para>To facilitate upgrades from a package version that shipped + only SysV init scripts to a package version that ships both a + SysV init script and a native systemd service file, use a + fragment like the following:</para> + + <programlisting>%triggerun -- foobar < 0.47.11-1 +if /sbin/chkconfig --level 5 foobar ; then + /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : +fi</programlisting> + + <para>Where 0.47.11-1 is the first package version that includes + the native unit file. This fragment will ensure that the first + time the unit file is installed, it will be enabled if and only + if the SysV init script is enabled, thus making sure that the + enable status is not changed. Note that + <command>chkconfig</command> is a command specific to Fedora + which can be used to check whether a SysV init script is + enabled. Other operating systems will have to use different + commands here.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Porting Existing Daemons</title> + + <para>Since new-style init systems such as systemd are compatible + with traditional SysV init systems, it is not strictly necessary + to port existing daemons to the new style. However, doing so + offers additional functionality to the daemons as well as + simplifying integration into new-style init systems.</para> + + <para>To port an existing SysV compatible daemon, the following + steps are recommended:</para> + + <orderedlist> + <listitem><para>If not already implemented, add an optional + command line switch to the daemon to disable daemonization. This + is useful not only for using the daemon in new-style init + systems, but also to ease debugging.</para></listitem> + + <listitem><para>If the daemon offers interfaces to other + software running on the local system via local + <constant>AF_UNIX</constant> sockets, consider implementing + socket-based activation (see above). Usually, a minimal patch is + sufficient to implement this: Extend the socket creation in the + daemon code so that + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is checked for already passed sockets first. If sockets are + passed (i.e. when <function>sd_listen_fds()</function> returns a + positive value), skip the socket creation step and use the + passed sockets. Secondly, ensure that the file system socket + nodes for local <constant>AF_UNIX</constant> sockets used in the + socket-based activation are not removed when the daemon shuts + down, if sockets have been passed. Third, if the daemon normally + closes all remaining open file descriptors as part of its + initialization, the sockets passed from the init system must be + spared. Since new-style init systems guarantee that no left-over + file descriptors are passed to executed processes, it might be a + good choice to simply skip the closing of all remaining open + file descriptors if sockets are passed.</para></listitem> + + <listitem><para>Write and install a systemd unit file for the + service (and the sockets if socket-based activation is used, as + well as a path unit file, if the daemon processes a spool + directory), see above for details.</para></listitem> + + <listitem><para>If the daemon exposes interfaces via D-Bus, + write and install a D-Bus activation file for the service, see + above for details.</para></listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Placing Daemon Data</title> + + <para>It is recommended to follow the general guidelines for + placing package files, as discussed in + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/dnssec-trust-anchors.d.xml b/src/manpages/dnssec-trust-anchors.d.xml new file mode 100644 index 0000000000..4bdc167f79 --- /dev/null +++ b/src/manpages/dnssec-trust-anchors.d.xml @@ -0,0 +1,200 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>dnssec-trust-anchors.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>dnssec-trust-anchors.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>dnssec-trust-anchors.d</refname> + <refname>systemd.positive</refname> + <refname>systemd.negative</refname> + <refpurpose>DNSSEC trust anchor configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para> + <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para> + <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The DNSSEC trust anchor configuration files define positive + and negative trust anchors + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + bases DNSSEC integrity proofs on.</para> + </refsect1> + + <refsect1> + <title>Positive Trust Anchors</title> + + <para>Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See <ulink + url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, + Section 4.4</ulink> for more information about DNSSEC trust + anchors.</para> + + <para>Positive trust anchors are read from files with the suffix + <filename>.positive</filename> located in + <filename>/etc/dnssec-trust-anchors.d/</filename>, + <filename>/run/dnssec-trust-anchors.d/</filename> and + <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These + directories are searched in the specified order, and a trust + anchor file of the same name in an earlier path overrides a trust + anchor files in a later path. To disable a trust anchor file + shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename> + it is sufficient to provide an identically-named file in + <filename>/etc/dnssec-trust-anchors.d/</filename> or + <filename>/run/dnssec-trust-anchors.d/</filename> that is either + empty or a symlink to <filename>/dev/null</filename> ("masked").</para> + + <para>Positive trust anchor files are simple text files resembling + DNS zone files, as documented in <ulink + url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section + 5</ulink>. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with a semicolon + (<literal>;</literal>) are ignored and considered comments. A DS + resource record is specified like in the following example:</para> + + <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> + + <para>The first word specifies the domain, use + <literal>.</literal> for the root domain. The domain may be + specified with or without trailing dot, which is considered + equivalent. The second word must be <literal>IN</literal> the + third word <literal>DS</literal>. The following words specify the + key tag, signature algorithm, digest algorithm, followed by the + hex-encoded key fingerprint. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034, + Section 5</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>Alternatively, DNSKEY resource records may be used to define + trust anchors, like in the following example:</para> + + <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> + + <para>The first word specifies the domain again, the second word + must be <literal>IN</literal>, followed by + <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data + encoded in Base64. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, + Section 2</ulink> for details about the precise syntax and meaning + of these fields.</para> + + <para>If multiple DS or DNSKEY records are defined for the same + domain (possibly even in different trust anchor files), all keys + are used and are considered equivalent as base for DNSSEC + proofs.</para> + + <para>Note that <filename>systemd-resolved</filename> will + automatically use a built-in trust anchor key for the Internet + root domain if no positive trust anchors are defined for the root + domain. In most cases it is hence unnecessary to define an + explicit key with trust anchor files. The built-in key is disabled + as soon as at least one trust anchor key for the root domain is + defined in trust anchor files.</para> + + <para>It is generally recommended to encode trust anchors in DS + resource records, rather than DNSKEY resource records.</para> + + <para>If a trust anchor specified via a DS record is found revoked + it is automatically removed from the trust anchor database for the + runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC + 5011</ulink> for details about revoked trust anchors. Note that + <filename>systemd-resolved</filename> will not update its trust + anchor database from DNS servers automatically. Instead, it is + recommended to update the resolver software or update the new + trust anchor via adding in new trust anchor files.</para> + + <para>The current DNSSEC trust anchor for the Internet's root + domain is available at the <ulink + url="https://data.iana.org/root-anchors/root-anchors.xml">IANA + Trust Anchor and Keys</ulink> page.</para> + </refsect1> + + <refsect1> + <title>Negative Trust Anchors</title> + + <para>Negative trust anchors define domains where DNSSEC + validation shall be turned off. Negative trust anchor files are + found at the same location as positive trust anchor files, and + follow the same overriding rules. They are text files with the + <filename>.negative</filename> suffix. Empty lines and lines whose + first character is <literal>;</literal> are ignored. Each line + specifies one domain name where DNSSEC validation shall be + disabled on.</para> + + <para>Negative trust anchors are useful to support private DNS + subtrees that are not referenced from the Internet DNS hierarchy, + and not signed.</para> + + <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC + 7646</ulink> for details on negative trust anchors.</para> + + <para>If no negative trust anchor files are configured a built-in + set of well-known private DNS zone domains is used as negative + trust anchors.</para> + + <para>It is also possibly to define per-interface negative trust + anchors using the <varname>DNSSECNegativeTrustAnchors=</varname> + setting in + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/file-hierarchy.xml b/src/manpages/file-hierarchy.xml new file mode 100644 index 0000000000..538a592f8d --- /dev/null +++ b/src/manpages/file-hierarchy.xml @@ -0,0 +1,815 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="file-hierarchy"> + + <refentryinfo> + <title>file-hierarchy</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>file-hierarchy</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>file-hierarchy</refname> + <refpurpose>File system hierarchy overview</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Operating systems using the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + system and service manager are organized based on a file system + hierarchy inspired by UNIX, more specifically the hierarchy + described in the <ulink + url="http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html">File + System Hierarchy</ulink> specification and + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + This manual page describes a more minimal, modernized subset of + these specifications that defines more strictly the suggestions + and restrictions systemd makes on the file system + hierarchy.</para> + + <para>Many of the paths described here can be queried + with the + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</para> + </refsect1> + + <refsect1> + <title>General Structure</title> + + <variablelist> + <varlistentry> + <term><filename>/</filename></term> + <listitem><para>The file system root. Usually writable, but + this is not required. Possibly a temporary file system + (<literal>tmpfs</literal>). Not shared with other hosts + (unless read-only). </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/boot</filename></term> + <listitem><para>The boot partition used for bringing up the + system. On EFI systems, this is possibly the EFI System + Partition, also see + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This directory is usually strictly local to the host, and + should be considered read-only, except when a new kernel or + boot loader is installed. This directory only exists on + systems that run on physical or emulated hardware that + requires boot loaders.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/etc</filename></term> + <listitem><para>System-specific configuration. This directory + may or may not be read-only. Frequently, this directory is + pre-populated with vendor-supplied configuration files, but + applications should not make assumptions about this directory + being fully populated or populated at all, and should fall + back to defaults if configuration is + missing.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/home</filename></term> + <listitem><para>The location for normal user's home + directories. Possibly shared with other systems, and never + read-only. This directory should only be used for normal + users, never for system users. This directory and possibly the + directories contained within it might only become available or + writable in late boot or even only after user authentication. + This directory might be placed on limited-functionality + network file systems, hence applications should not assume the + full set of file API is available on this directory. + Applications should generally not reference this directory + directly, but via the per-user <varname>$HOME</varname> + environment variable, or via the home directory field of the + user database.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/root</filename></term> + <listitem><para>The home directory of the root user. The root + user's home directory is located outside of + <filename>/home</filename> in order to make sure the root user + may log in even without <filename>/home</filename> being + available and mounted.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/srv</filename></term> + <listitem><para>The place to store general server payload, + managed by the administrator. No restrictions are made how + this directory is organized internally. Generally writable, + and possibly shared among systems. This directory might become + available or writable only very late during + boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/tmp</filename></term> + <listitem><para>The place for small temporary files. This + directory is usually mounted as a <literal>tmpfs</literal> + instance, and should hence not be used for larger files. (Use + <filename>/var/tmp</filename> for larger files.) Since the + directory is accessible to other users of the system, it is + essential that this directory is only written to with the + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls. This directory is usually flushed at + boot-up. Also, files that are not accessed within a certain + time are usually automatically deleted. If applications find + the environment variable <varname>$TMPDIR</varname> set, they + should prefer using the directory specified in it over + directly referencing <filename>/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE + Std 1003.1</ulink> for details).</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Runtime Data</title> + + <variablelist> + <varlistentry> + <term><filename>/run</filename></term> + <listitem><para>A <literal>tmpfs</literal> file system for + system packages to place runtime data in. This directory is + flushed on boot, and generally writable for privileged + programs only. Always writable.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/log</filename></term> + <listitem><para>Runtime system logs. System components may + place private logs in this directory. Always writable, even + when <filename>/var/log</filename> might not be accessible + yet.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/user</filename></term> + <listitem><para>Contains per-user runtime directories, each + usually individually mounted <literal>tmpfs</literal> + instances. Always writable, flushed at each reboot and when + the user logs out. User code should not reference this + directory directly, but via the + <varname>$XDG_RUNTIME_DIR</varname> environment variable, as + documented in the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Vendor-supplied Operating System Resources</title> + + <variablelist> + + <varlistentry> + <term><filename>/usr</filename></term> + <listitem><para>Vendor-supplied operating system resources. + Usually read-only, but this is not required. Possibly shared + between multiple hosts. This directory should not be modified + by the administrator, except when installing or removing + vendor-supplied packages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/bin</filename></term> + <listitem><para>Binaries and executables for user commands + that shall appear in the <varname>$PATH</varname> search path. + It is recommended not to place binaries in this directory that + are not useful for invocation from a shell (such as daemon + binaries); these should be placed in a subdirectory of + <filename>/usr/lib</filename> instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/include</filename></term> + <listitem><para>C and C++ API header files of system + libraries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib</filename></term> + <listitem><para>Static, private vendor data that is compatible + with all architectures (though not necessarily + architecture-independent). Note that this includes internal + executables or other binaries that are not regularly invoked + from a shell. Such binaries may be for any architecture + supported by the system. Do not place public libraries in this + directory, use <varname>$libdir</varname> (see below), + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term> + <listitem><para>Location for placing dynamic libraries into, also + called <varname>$libdir</varname>. The architecture identifier + to use is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> list. Legacy + locations of <varname>$libdir</varname> are + <filename>/usr/lib</filename>, + <filename>/usr/lib64</filename>. This directory should not be + used for package-specific data, unless this data is + architecture-dependent, too. To query + <varname>$libdir</varname> for the primary architecture of the + system, invoke: + <programlisting># systemd-path system-library-arch</programlisting></para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/usr/share</filename></term> + <listitem><para>Resources shared between multiple packages, + such as documentation, man pages, time zone information, fonts + and other resources. Usually, the precise location and format + of files stored below this directory is subject to + specifications that ensure interoperability.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/doc</filename></term> + <listitem><para>Documentation for the operating system or + system packages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/etc</filename></term> + <listitem><para>Repository for vendor-supplied default + configuration files. This directory should be populated with + pristine vendor versions of all configuration files that may + be placed in <filename>/etc</filename>. This is useful to + compare the local configuration of a system with vendor + defaults and to populate the local configuration with + defaults.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/var</filename></term> + + <listitem><para>Similar to + <filename>/usr/share/factory/etc</filename>, but for vendor + versions of files in the variable, persistent data directory + <filename>/var</filename>.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Persistent Variable System Data</title> + + <variablelist> + <varlistentry> + <term><filename>/var</filename></term> + <listitem><para>Persistent, variable system data. Must be + writable. This directory might be pre-populated with + vendor-supplied data, but applications should be able to + reconstruct necessary files and directories in this + subhierarchy should they be missing, as the system might start + up without this directory being populated. Persistency is + recommended, but optional, to support ephemeral systems. This + directory might become available or writable only very late + during boot. Components that are required to operate during + early boot hence shall not unconditionally rely on this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/cache</filename></term> + <listitem><para>Persistent system cache data. System + components may place non-essential data in this directory. + Flushing this directory should have no effect on operation of + programs, except for increased runtimes necessary to rebuild + these caches.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/lib</filename></term> + <listitem><para>Persistent system data. System components may + place private data in this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/log</filename></term> + <listitem><para>Persistent system logs. System components may + place private logs in this directory, though it is recommended + to do most logging via the + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> + calls.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/spool</filename></term> + <listitem><para>Persistent system spool data, such as printer + or mail queues.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/tmp</filename></term> + <listitem><para>The place for larger and persistent temporary + files. In contrast to <filename>/tmp</filename>, this directory + is usually mounted from a persistent physical file system and + can thus accept larger files. (Use <filename>/tmp</filename> + for smaller files.) This directory is generally not flushed at + boot-up, but time-based cleanup of files that have not been + accessed for a certain time is applied. The same security + restrictions as with <filename>/tmp</filename> apply, and + hence only + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar calls should be used to make use of this directory. + If applications find the environment variable + <varname>$TMPDIR</varname> set, they should prefer using the + directory specified in it over directly referencing + <filename>/var/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Virtual Kernel and API File Systems</title> + + <variablelist> + <varlistentry> + <term><filename>/dev</filename></term> + <listitem><para>The root directory for device nodes. Usually, + this directory is mounted as a <literal>devtmpfs</literal> + instance, but might be of a different type in + sandboxed/containerized setups. This directory is managed + jointly by the kernel and + <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + and should not be written to by other components. A number of + special purpose virtual file systems might be mounted below + this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/shm</filename></term> + <listitem><para>Place for POSIX shared memory segments, as + created via + <citerefentry project='die-net'><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This directory is flushed on boot, and is a + <literal>tmpfs</literal> file system. Since all users have + write access to this directory, special care should be taken + to avoid name clashes and vulnerabilities. For normal users, + shared memory segments in this directory are usually deleted + when the user logs out. Usually, it is a better idea to use + memory mapped files in <filename>/run</filename> (for system + programs) or <varname>$XDG_RUNTIME_DIR</varname> (for user + programs) instead of POSIX shared memory segments, since these + directories are not world-writable and hence not vulnerable to + security-sensitive name clashes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc</filename></term> + <listitem><para>A virtual kernel file system exposing the + process list and other functionality. This file system is + mostly an API to interface with the kernel and not a place + where normal files may be stored. For details, see + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + A number of special purpose virtual file systems might be + mounted below this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc/sys</filename></term> + <listitem><para>A hierarchy below <filename>/proc</filename> + that exposes a number of kernel tunables. The primary way to + configure the settings in this API file tree is via + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files. In sandboxed/containerized setups, this directory is + generally mounted read-only.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/sys</filename></term> + <listitem><para>A virtual kernel file system exposing + discovered devices and other functionality. This file system + is mostly an API to interface with the kernel and not a place + where normal files may be stored. In sandboxed/containerized + setups, this directory is generally mounted read-only. A number + of special purpose virtual file systems might be mounted below + this directory.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Compatibility Symlinks</title> + + <variablelist> + <varlistentry> + <term><filename>/bin</filename></term> + <term><filename>/sbin</filename></term> + <term><filename>/usr/sbin</filename></term> + + <listitem><para>These compatibility symlinks point to + <filename>/usr/bin</filename>, ensuring that scripts and + binaries referencing these legacy paths correctly find their + binaries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/usr/lib</filename>, ensuring that programs + referencing this legacy path correctly find their + resources.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib64</filename></term> + + <listitem><para>On some architecture ABIs, this compatibility + symlink points to <varname>$libdir</varname>, ensuring that + binaries referencing this legacy path correctly find their + dynamic loader. This symlink only exists on architectures + whose ABI places the dynamic loader in this + path.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/run</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/run</filename>, ensuring that programs referencing + this legacy path correctly find their runtime + data.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Home Directory</title> + + <para>User applications may want to place files and directories in + the user's home directory. They should follow the following basic + structure. Note that some of these directories are also + standardized (though more weakly) by the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>. Additional locations for + high-level user resources are defined by <ulink + url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para> + + <variablelist> + <varlistentry> + <term><filename>~/.cache</filename></term> + + <listitem><para>Persistent user cache data. User programs may + place non-essential data in this directory. Flushing this + directory should have no effect on operation of programs, + except for increased runtimes necessary to rebuild these + caches. If an application finds + <varname>$XDG_CACHE_HOME</varname> set, it should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.config</filename></term> + + <listitem><para>Application configuration and state. When a + new user is created, this directory will be empty or not exist + at all. Applications should fall back to defaults should their + configuration or state in this directory be missing. If an + application finds <varname>$XDG_CONFIG_HOME</varname> set, it + should use the directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/bin</filename></term> + + <listitem><para>Executables that shall appear in the user's + <varname>$PATH</varname> search path. It is recommended not to + place executables in this directory that are not useful for + invocation from a shell; these should be placed in a + subdirectory of <filename>~/.local/lib</filename> instead. + Care should be taken when placing architecture-dependent + binaries in this place, which might be problematic if the home + directory is shared between multiple hosts with different + architectures.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib</filename></term> + + <listitem><para>Static, private vendor data that is compatible + with all architectures.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term> + + <listitem><para>Location for placing public dynamic libraries. + The architecture identifier to use is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/share</filename></term> + + <listitem><para>Resources shared between multiple packages, + such as fonts or artwork. Usually, the precise location and + format of files stored below this directory is subject to + specifications that ensure interoperability. If an application + finds <varname>$XDG_DATA_HOME</varname> set, it should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + + <refsect1> + <title>Unprivileged Write Access</title> + + <para>Unprivileged processes generally lack write access to most + of the hierarchy.</para> + + <para>The exceptions for normal users are + <filename>/tmp</filename>, + <filename>/var/tmp</filename>, + <filename>/dev/shm</filename>, as well as the home directory + <varname>$HOME</varname> (usually found below + <filename>/home</filename>) and the runtime directory + <varname>$XDG_RUNTIME_DIR</varname> (found below + <filename>/run/user</filename>) of the user, which are all + writable.</para> + + <para>For unprivileged system processes, only + <filename>/tmp</filename>, + <filename>/var/tmp</filename> and + <filename>/dev/shm</filename> are writable. If an + unprivileged system process needs a private writable directory in + <filename>/var</filename> or <filename>/run</filename>, it is + recommended to either create it before dropping privileges in the + daemon code, to create it via + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + fragments during boot, or via the + <varname>RuntimeDirectory=</varname> directive of service units + (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + </refsect1> + + <refsect1> + <title>Node Types</title> + + <para>Unix file systems support different types of file nodes, + including regular files, directories, symlinks, character and + block device nodes, sockets and FIFOs.</para> + + <para>It is strongly recommended that <filename>/dev</filename> is + the only location below which device nodes shall be placed. + Similarly, <filename>/run</filename> shall be the only location to + place sockets and FIFOs. Regular files, directories and symlinks + may be used in all directories.</para> + </refsect1> + + <refsect1> + <title>System Packages</title> + + <para>Developers of system packages should follow strict rules + when placing their own files in the file system. The following + table lists recommended locations for specific types of files + supplied by the vendor.</para> + + <table> + <title>System Package Vendor Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/usr/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry> + </row> + <row> + <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry> + <entry>Public C/C++ APIs of public shared libraries of the package.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>/usr/share</filename> hierarchy to the locations + defined by the various relevant specifications.</para> + + <para>During runtime, and for local configuration and state, + additional directories are defined:</para> + + <table> + <title>System Package Variable Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/etc/<replaceable>package</replaceable></filename></entry> + <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry> + </row> + <row> + <entry><filename>/run/<replaceable>package</replaceable></filename></entry> + <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry> + </row> + <row> + <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry> + <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry> + </row> + <row> + <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry> + <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + </row> + <row> + <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry> + <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry> + </row> + <row> + <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry> + <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> + </row> + <row> + <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry> + <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>User Packages</title> + + <para>Programs running in user context should follow strict rules + when placing their own files in the user's home directory. The + following table lists recommended locations in the home directory + for specific types of files supplied by the vendor if the + application is installed in the home directory. (Note, however, + that user applications installed system-wide should follow the + rules outlined above regarding placing vendor files.)</para> + + <table> + <title>User Package Vendor File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.local/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>~/.local/share</filename> hierarchy to the locations + defined by the various relevant specifications.</para> + + <para>During runtime, and for local configuration and state, + additional directories are defined:</para> + + <table> + <title>User Package Variable File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry> + <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry> + </row> + <row> + <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry> + <entry>User runtime data for the package.</entry> + </row> + <row> + <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry> + <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/glib-event-glue.c b/src/manpages/glib-event-glue.c new file mode 100644 index 0000000000..8f3168d0ea --- /dev/null +++ b/src/manpages/glib-event-glue.c @@ -0,0 +1,68 @@ +/*** + Copyright 2014 Tom Gundersen + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation files + (the "Software"), to deal in the Software without restriction, + including without limitation the rights to use, copy, modify, merge, + publish, distribute, sublicense, and/or sell copies of the Software, + and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +***/ + +#include <stdlib.h> + +typedef struct SDEventSource { + GSource source; + GPollFD pollfd; + sd_event *event; +} SDEventSource; + +static gboolean event_prepare(GSource *source, gint *timeout_) { + return sd_event_prepare(((SDEventSource *)source)->event) > 0; +} + +static gboolean event_check(GSource *source) { + return sd_event_wait(((SDEventSource *)source)->event, 0) > 0; +} + +static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) { + return sd_event_dispatch(((SDEventSource *)source)->event) > 0; +} + +static void event_finalize(GSource *source) { + sd_event_unref(((SDEventSource *)source)->event); +} + +static GSourceFuncs event_funcs = { + .prepare = event_prepare, + .check = event_check, + .dispatch = event_dispatch, + .finalize = event_finalize, +}; + +GSource *g_sd_event_create_source(sd_event *event) { + SDEventSource *source; + + source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource)); + + source->event = sd_event_ref(event); + source->pollfd.fd = sd_event_get_fd(event); + source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR; + + g_source_add_poll((GSource *)source, &source->pollfd); + + return (GSource *)source; +} diff --git a/src/manpages/halt.xml b/src/manpages/halt.xml new file mode 100644 index 0000000000..e3fa60a915 --- /dev/null +++ b/src/manpages/halt.xml @@ -0,0 +1,176 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="halt" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>halt</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>halt</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>halt</refname> + <refname>poweroff</refname> + <refname>reboot</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>halt</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>poweroff</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>reboot</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>halt</command>, <command>poweroff</command>, + <command>reboot</command> may be used to halt, power-off or reboot + the machine.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine, regardless of which one of + the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the machine, regardless of which one + of the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the machine, regardless of which one of + the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + <term><option>--force</option></term> + + <listitem><para>Force immediate halt, power-off, reboot. Do + not contact the init system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + <term><option>--wtmp-only</option></term> + + <listitem><para>Only write wtmp shutdown entry, do not + actually halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--no-wtmp</option></term> + + <listitem><para>Do not write wtmp shutdown + entry.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--no-sync</option></term> + + <listitem><para>Don't sync hard disks/storage media before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall message before halt, + power-off, reboot.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These are legacy commands available for compatibility + only.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/hostname.xml b/src/manpages/hostname.xml new file mode 100644 index 0000000000..8a4c0d5ac0 --- /dev/null +++ b/src/manpages/hostname.xml @@ -0,0 +1,98 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="hostname"> + <refentryinfo> + <title>hostname</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>hostname</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostname</refname> + <refpurpose>Local hostname configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/hostname</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/hostname</filename> file configures the + name of the local system that is set during boot using the + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call. It should contain a single newline-terminated + hostname string. Comments (lines starting with a `#') are ignored. + The hostname may be a free-form string up to 64 characters in length; + however, it is recommended that it consists only of 7-bit ASCII lower-case + characters and no spaces or dots, and limits itself to the format allowed + for DNS domain name labels, even though this is not a strict + requirement.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the value of this file during runtime from the command + line. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/hostname</filename> originates from Debian + GNU/Linux.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/hwdb.xml b/src/manpages/hwdb.xml new file mode 100644 index 0000000000..2b1e60fb22 --- /dev/null +++ b/src/manpages/hwdb.xml @@ -0,0 +1,85 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<refentry id="hwdb" conditional="ENABLE_HWDB"> + <refentryinfo> + <title>hwdb</title> + <productname>systemd</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>hwdb</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>hwdb</refname> + <refpurpose>Hardware Database</refpurpose> + </refnamediv> + + <refsect1><title>Description</title> + <para>The hardware database is a key-value store for associating modalias-like keys to + udev-property-like values. It is used primarily by udev to add the relevant properties + to matching devices, but it can also be queried directly.</para> + </refsect1> + + <refsect1><title>Hardware Database Files</title> + <para>The hwdb files are read from the files located in the + system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename> and + the local administration directory <filename>/etc/udev/hwdb.d</filename>. + All hwdb files are collectively sorted and processed in lexical order, + regardless of the directories in which they live. However, files with + identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority and take precedence over files with the same + name in <filename>/usr/lib</filename>. This can be used to override a + system-supplied hwdb file with a local file if needed; + a symlink in <filename>/etc</filename> with the same name as a hwdb file in + <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, + disables the hwdb file entirely. hwdb files must have the extension + <filename>.hwdb</filename>; other extensions are ignored.</para> + + <para>The hwdb file contains data records consisting of matches and + associated key-value pairs. Every record in the hwdb starts with one or + more match strings, specifying a shell glob to compare the database + lookup string against. Multiple match lines are specified in additional + consecutive lines. Every match line is compared individually, and they are + combined by OR. Every match line must start at the first character of + the line.</para> + + <para>The match lines are followed by one or more key-value pair lines, which + are recognized by a leading space character. The key name and value are separated + by <literal>=</literal>. An empty line signifies the end + of a record. Lines beginning with <literal>#</literal> are ignored.</para> + + <para>The content of all hwdb files is read by + <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>, + or alternatively <filename>/usr/lib/udev/hwdb.bin</filename> if you want ship the compiled + database in an immutable image. + During runtime, only the binary database is used.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry> + <refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry> diff --git a/src/manpages/journal-remote.conf.xml b/src/manpages/journal-remote.conf.xml new file mode 100644 index 0000000000..2d345963d9 --- /dev/null +++ b/src/manpages/journal-remote.conf.xml @@ -0,0 +1,121 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Chris Morgan + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journal-remote.conf" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>journal-remote.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Chris</firstname> + <surname>Morgan</surname> + <email>chmorgan@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journal-remote.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journal-remote.conf</refname> + <refname>journal-remote.conf.d</refname> + <refpurpose>Journal remote service configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/journal-remote.conf</filename></para> + <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd-remote-journal + application, + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Remote]</literal> section:</para> + + <variablelist> + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Periodically sign the data in the journal using Forward Secure Sealing. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>SplitMode=</varname></term> + + <listitem><para>One of <literal>host</literal> or <literal>none</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerKeyFile=</varname></term> + + <listitem><para>SSL key in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TrustedCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/journald.conf.xml b/src/manpages/journald.conf.xml new file mode 100644 index 0000000000..3964cd6bc5 --- /dev/null +++ b/src/manpages/journald.conf.xml @@ -0,0 +1,410 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journald.conf" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>journald.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journald.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journald.conf</refname> + <refname>journald.conf.d</refname> + <refpurpose>Journal service configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/journald.conf</filename></para> + <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd + journal service, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Journal]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>Storage=</varname></term> + + <listitem><para>Controls where to store journal data. One of + <literal>volatile</literal>, + <literal>persistent</literal>, + <literal>auto</literal> and + <literal>none</literal>. If + <literal>volatile</literal>, journal + log data will be stored only in memory, i.e. below the + <filename>/run/log/journal</filename> hierarchy (which is + created if needed). If <literal>persistent</literal>, data + will be stored preferably on disk, i.e. below the + <filename>/var/log/journal</filename> hierarchy (which is + created if needed), with a fallback to + <filename>/run/log/journal</filename> (which is created if + needed), during early boot and if the disk is not writable. + <literal>auto</literal> is similar to + <literal>persistent</literal> but the directory + <filename>/var/log/journal</filename> is not created if + needed, so that its existence controls where log data goes. + <literal>none</literal> turns off all storage, all log data + received will be dropped. Forwarding to other targets, such as + the console, the kernel log buffer, or a syslog socket will + still work however. Defaults to + <literal>auto</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Compress=</varname></term> + + <listitem><para>Takes a boolean value. If enabled (the + default), data objects that shall be stored in the journal and + are larger than a certain threshold are compressed before they + are written to the file system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Takes a boolean value. If enabled (the + default), and a sealing key is available (as created by + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--setup-keys</option> command), Forward Secure Sealing + (FSS) for all persistent journal files is enabled. FSS is + based on <ulink + url="https://eprint.iacr.org/2013/397">Seekable Sequential Key + Generators</ulink> by G. A. Marson and B. Poettering + (doi:10.1007/978-3-642-40203-6_7) and may be used to protect + journal files from unnoticed alteration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SplitMode=</varname></term> + + <listitem><para>Controls whether to split up journal files per + user. One of <literal>uid</literal>, <literal>login</literal> + and <literal>none</literal>. If <literal>uid</literal>, all + users will get each their own journal files regardless of + whether they possess a login session or not, however system + users will log into the system journal. If + <literal>login</literal>, actually logged-in users will get + each their own journal files, but users without login session + and system users will log into the system journal. If + <literal>none</literal>, journal files are not split up by + user and all messages are instead stored in the single system + journal. Note that splitting up journal files by user is only + available for journals stored persistently. If journals are + stored on volatile storage (see above), only a single journal + file for all user IDs is kept. Defaults to + <literal>uid</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RateLimitIntervalSec=</varname></term> + <term><varname>RateLimitBurst=</varname></term> + + <listitem><para>Configures the rate limiting that is applied + to all messages generated on the system. If, in the time + interval defined by <varname>RateLimitIntervalSec=</varname>, + more messages than specified in + <varname>RateLimitBurst=</varname> are logged by a service, + all further messages within the interval are dropped until the + interval is over. A message about the number of dropped + messages is generated. This rate limiting is applied + per-service, so that two services which log do not interfere + with each other's limits. Defaults to 1000 messages in 30s. + The time specification for + <varname>RateLimitIntervalSec=</varname> may be specified in the + following units: <literal>s</literal>, <literal>min</literal>, + <literal>h</literal>, <literal>ms</literal>, + <literal>us</literal>. To turn off any kind of rate limiting, + set either value to 0.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemMaxUse=</varname></term> + <term><varname>SystemKeepFree=</varname></term> + <term><varname>SystemMaxFileSize=</varname></term> + <term><varname>SystemMaxFiles=</varname></term> + <term><varname>RuntimeMaxUse=</varname></term> + <term><varname>RuntimeKeepFree=</varname></term> + <term><varname>RuntimeMaxFileSize=</varname></term> + <term><varname>RuntimeMaxFiles=</varname></term> + + <listitem><para>Enforce size limits on the journal files + stored. The options prefixed with <literal>System</literal> + apply to the journal files when stored on a persistent file + system, more specifically + <filename>/var/log/journal</filename>. The options prefixed + with <literal>Runtime</literal> apply to the journal files + when stored on a volatile in-memory file system, more + specifically <filename>/run/log/journal</filename>. The former + is used only when <filename>/var</filename> is mounted, + writable, and the directory + <filename>/var/log/journal</filename> exists. Otherwise, only + the latter applies. Note that this means that during early + boot and if the administrator disabled persistent logging, + only the latter options apply, while the former apply if + persistent logging is enabled and the system is fully booted + up. <command>journalctl</command> and + <command>systemd-journald</command> ignore all files with + names not ending with <literal>.journal</literal> or + <literal>.journal~</literal>, so only such files, located in + the appropriate directories, are taken into account when + calculating current disk usage.</para> + + <para><varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname> control how much disk space + the journal may use up at most. + <varname>SystemKeepFree=</varname> and + <varname>RuntimeKeepFree=</varname> control how much disk + space systemd-journald shall leave free for other uses. + <command>systemd-journald</command> will respect both limits + and use the smaller of the two values.</para> + + <para>The first pair defaults to 10% and the second to 15% of + the size of the respective file system, but each value is + capped to 4G. If the file system is nearly full and either + <varname>SystemKeepFree=</varname> or + <varname>RuntimeKeepFree=</varname> are violated when + systemd-journald is started, the limit will be raised to the + percentage that is actually free. This means that if there was + enough free space before and journal files were created, and + subsequently something else causes the file system to fill up, + journald will stop using more space, but it will not be + removing existing files to reduce the footprint again, + either.</para> + + <para><varname>SystemMaxFileSize=</varname> and + <varname>RuntimeMaxFileSize=</varname> control how large + individual journal files may grow at most. This influences + the granularity in which disk space is made available through + rotation, i.e. deletion of historic data. Defaults to one + eighth of the values configured with + <varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname>, so that usually seven + rotated journal files are kept as history.</para> + + <para>Specify values in bytes or use K, M, G, T, P, E as + units for the specified sizes (equal to 1024, 1024², ... bytes). + Note that size limits are enforced synchronously when journal + files are extended, and no explicit rotation step triggered by + time is needed.</para> + + <para><varname>SystemMaxFiles=</varname> and + <varname>RuntimeMaxFiles=</varname> control how many + individual journal files to keep at most. Note that only + archived files are deleted to reduce the number of files until + this limit is reached; active files will stay around. This + means that, in effect, there might still be more journal files + around in total than this limit after a vacuuming operation is + complete. This setting defaults to 100.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxFileSec=</varname></term> + + <listitem><para>The maximum time to store entries in a single + journal file before rotating to the next one. Normally, + time-based rotation should not be required as size-based + rotation with options such as + <varname>SystemMaxFileSize=</varname> should be sufficient to + ensure that journal files do not grow without bounds. However, + to ensure that not too much data is lost at once when old + journal files are deleted, it might make sense to change this + value from the default of one month. Set to 0 to turn off this + feature. This setting takes time values which may be suffixed + with the units <literal>year</literal>, + <literal>month</literal>, <literal>week</literal>, + <literal>day</literal>, <literal>h</literal> or + <literal>m</literal> to override the default time unit of + seconds.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxRetentionSec=</varname></term> + + <listitem><para>The maximum time to store journal entries. + This controls whether journal files containing entries older + then the specified time span are deleted. Normally, time-based + deletion of old journal files should not be required as + size-based deletion with options such as + <varname>SystemMaxUse=</varname> should be sufficient to + ensure that journal files do not grow without bounds. However, + to enforce data retention policies, it might make sense to + change this value from the default of 0 (which turns off this + feature). This setting also takes time values which may be + suffixed with the units <literal>year</literal>, + <literal>month</literal>, <literal>week</literal>, + <literal>day</literal>, <literal>h</literal> or <literal> + m</literal> to override the default time unit of + seconds.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>SyncIntervalSec=</varname></term> + + <listitem><para>The timeout before synchronizing journal files + to disk. After syncing, journal files are placed in the + OFFLINE state. Note that syncing is unconditionally done + immediately after a log message of priority CRIT, ALERT or + EMERG has been logged. This setting hence applies only to + messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The + default timeout is 5 minutes. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForwardToSyslog=</varname></term> + <term><varname>ForwardToKMsg=</varname></term> + <term><varname>ForwardToConsole=</varname></term> + <term><varname>ForwardToWall=</varname></term> + + <listitem><para>Control whether log messages received by the + journal daemon shall be forwarded to a traditional syslog + daemon, to the kernel log buffer (kmsg), to the system + console, or sent as wall messages to all logged-in users. + These options take boolean arguments. If forwarding to syslog + is enabled but nothing reads messages from the socket, + forwarding to syslog has no effect. By default, only + forwarding to wall is enabled. These settings may be + overridden at boot time with the kernel command line options + <literal>systemd.journald.forward_to_syslog=</literal>, + <literal>systemd.journald.forward_to_kmsg=</literal>, + <literal>systemd.journald.forward_to_console=</literal>, and + <literal>systemd.journald.forward_to_wall=</literal>. When + forwarding to the console, the TTY to log to can be changed + with <varname>TTYPath=</varname>, described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxLevelStore=</varname></term> + <term><varname>MaxLevelSyslog=</varname></term> + <term><varname>MaxLevelKMsg=</varname></term> + <term><varname>MaxLevelConsole=</varname></term> + <term><varname>MaxLevelWall=</varname></term> + + <listitem><para>Controls the maximum log level of messages + that are stored on disk, forwarded to syslog, kmsg, the + console or wall (if that is enabled, see above). As argument, + takes one of + <literal>emerg</literal>, + <literal>alert</literal>, + <literal>crit</literal>, + <literal>err</literal>, + <literal>warning</literal>, + <literal>notice</literal>, + <literal>info</literal>, + <literal>debug</literal>, + or integer values in the range of 0–7 (corresponding to the + same levels). Messages equal or below the log level specified + are stored/forwarded, messages above are dropped. Defaults to + <literal>debug</literal> for <varname>MaxLevelStore=</varname> + and <varname>MaxLevelSyslog=</varname>, to ensure that the all + messages are written to disk and forwarded to syslog. Defaults + to + <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>, + <literal>info</literal> for <varname>MaxLevelConsole=</varname>, + and <literal>emerg</literal> for + <varname>MaxLevelWall=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TTYPath=</varname></term> + + <listitem><para>Change the console TTY to use if + <varname>ForwardToConsole=yes</varname> is used. Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Forwarding to traditional syslog daemons</title> + + <para> + Journal events can be transferred to a different logging daemon + in two different ways. With the first method, messages are + immediately forwarded to a socket + (<filename>/run/systemd/journal/syslog</filename>), where the + traditional syslog daemon can read them. This method is + controlled by the <varname>ForwardToSyslog=</varname> option. With a + second method, a syslog daemon behaves like a normal journal + client, and reads messages from the journal files, similarly to + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + With this, messages do not have to be read immediately, + which allows a logging daemon which is only started late in boot + to access all messages since the start of the system. In + addition, full structured meta-data is available to it. This + method of course is available only if the messages are stored in + a journal file at all. So it will not work if + <varname>Storage=none</varname> is set. It should be noted that + usually the <emphasis>second</emphasis> method is used by syslog + daemons, so the <varname>Storage=</varname> option, and not the + <varname>ForwardToSyslog=</varname> option, is relevant for them. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/kernel-command-line.xml b/src/manpages/kernel-command-line.xml new file mode 100644 index 0000000000..9c04849f66 --- /dev/null +++ b/src/manpages/kernel-command-line.xml @@ -0,0 +1,382 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="kernel-command-line"> + + <refentryinfo> + <title>kernel-command-line</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>kernel-command-line</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>kernel-command-line</refname> + <refpurpose>Kernel command line parameters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/proc/cmdline</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The kernel, the initial RAM disk (initrd) and + basic userspace functionality may be configured at boot via + kernel command line arguments.</para> + + <para>For command line parameters understood by the kernel, please + see <ulink + url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> + and + <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>For command line parameters understood by the initial RAM + disk, please see + <citerefentry project='man-pages'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + or the documentation of the specific initrd implementation of your + installation.</para> + </refsect1> + + <refsect1> + <title>Core OS Command Line Arguments</title> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + <term><varname>systemd.dump_core=</varname></term> + <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.crash_shell=</varname></term> + <term><varname>systemd.crash_reboot=</varname></term> + <term><varname>systemd.confirm_spawn=</varname></term> + <term><varname>systemd.show_status=</varname></term> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_color=</varname></term> + <term><varname>systemd.log_location=</varname></term> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <term><varname>systemd.setenv=</varname></term> + <term><varname>systemd.machine_id=</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager to control system behavior. For details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.mask=</varname></term> + <term><varname>systemd.wants=</varname></term> + <term><varname>systemd.debug-shell</varname></term> + <listitem> + <para>Additional parameters understood by + <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + to mask or start specific units at boot, or invoke a debug + shell on tty9.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.restore_state=</varname></term> + <listitem> + <para>This parameter is understood by several system tools + to control whether or not they should restore system state + from the previous boot. For details, see + <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + <listitem> + <para>Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>debug</varname></term> + <listitem> + <para>Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>-b</varname></term> + <term><varname>emergency</varname></term> + <term><varname>rescue</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager, as compatibility options. For details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager to control locale and language settings. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fsck.mode=</varname></term> + <term><varname>fsck.repair=</varname></term> + + <listitem> + <para>Parameters understood by the file system checker + services. For details, see + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quotacheck.mode=</varname></term> + + <listitem> + <para>Parameter understood by the file quota checker + service. For details, see + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.journald.forward_to_syslog=</varname></term> + <term><varname>systemd.journald.forward_to_kmsg=</varname></term> + <term><varname>systemd.journald.forward_to_console=</varname></term> + <term><varname>systemd.journald.forward_to_wall=</varname></term> + + <listitem> + <para>Parameters understood by the journal service. For + details, see + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap.toggle=</varname></term> + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font.map=</varname></term> + <term><varname>vconsole.font.unimap=</varname></term> + + <listitem> + <para>Parameters understood by the virtual console setup + logic. For details, see + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>udev.log-priority=</varname></term> + <term><varname>rd.udev.log-priority=</varname></term> + <term><varname>udev.children-max=</varname></term> + <term><varname>rd.udev.children-max=</varname></term> + <term><varname>udev.exec-delay=</varname></term> + <term><varname>rd.udev.exec-delay=</varname></term> + <term><varname>udev.event-timeout=</varname></term> + <term><varname>rd.udev.event-timeout=</varname></term> + <term><varname>net.ifnames=</varname></term> + + <listitem> + <para>Parameters understood by the device event managing + daemon. For details, see + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>plymouth.enable=</varname></term> + + <listitem> + <para>May be used to disable the Plymouth boot splash. For + details, see + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + <term><varname>luks.name=</varname></term> + <term><varname>rd.luks.name=</varname></term> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + <term><varname>luks.options=</varname></term> + <term><varname>rd.luks.options=</varname></term> + <term><varname>luks.key=</varname></term> + <term><varname>rd.luks.key=</varname></term> + + <listitem> + <para>Configures the LUKS full-disk encryption logic at + boot. For details, see + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fstab=</varname></term> + <term><varname>rd.fstab=</varname></term> + + <listitem> + <para>Configures the <filename>/etc/fstab</filename> logic + at boot. For details, see + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>root=</varname></term> + <term><varname>rootfstype=</varname></term> + <term><varname>rootflags=</varname></term> + <term><varname>ro</varname></term> + <term><varname>rw</varname></term> + + <listitem> + <para>Configures the root file system and its file system + type and mount options, as well as whether it shall be + mounted read-only or read-writable initially. For details, + see + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.gpt_auto=</varname></term> + <term><varname>rd.systemd.gpt_auto=</varname></term> + + <listitem> + <para>Configures whether GPT based partition auto-discovery + shall be attempted. For details, see + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.default_timeout_start_sec=</varname></term> + + <listitem> + <para>Overwrites the default start job timeout <varname>DefaultTimeoutStartSec=</varname> at boot. For details, + see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>modules-load=</varname></term> + <term><varname>rd.modules-load=</varname></term> + + <listitem> + <para>Load a specific kernel module early at boot. For + details, see + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>resume=</varname></term> + + <listitem> + <para>Enables resume from hibernation using the specified + device. All + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-like + paths are supported. For details, see + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/less-variables.xml b/src/manpages/less-variables.xml new file mode 100644 index 0000000000..0fb4d7fbcf --- /dev/null +++ b/src/manpages/less-variables.xml @@ -0,0 +1,29 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry id='pager'> + <term><varname>$SYSTEMD_PAGER</varname></term> + + <listitem><para>Pager to use when + <option>--no-pager</option> is not given; + overrides <varname>$PAGER</varname>. Setting + this to an empty string or the value + <literal>cat</literal> is equivalent to passing + <option>--no-pager</option>.</para></listitem> + </varlistentry> + + <varlistentry id='less'> + <term><varname>$SYSTEMD_LESS</varname></term> + + <listitem><para>Override the default + options passed to + <command>less</command> + (<literal>FRSXMK</literal>).</para></listitem> + </varlistentry> + </variablelist> +</refsect1> diff --git a/src/manpages/libsystemd-pkgconfig.xml b/src/manpages/libsystemd-pkgconfig.xml new file mode 100644 index 0000000000..272da64cd7 --- /dev/null +++ b/src/manpages/libsystemd-pkgconfig.xml @@ -0,0 +1,12 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<refsect1> + <title>Notes</title> + + <para id='pkgconfig-text'>These APIs are implemented as a shared + library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> +</refsect1> diff --git a/src/manpages/locale.conf.xml b/src/manpages/locale.conf.xml new file mode 100644 index 0000000000..2fe731113a --- /dev/null +++ b/src/manpages/locale.conf.xml @@ -0,0 +1,152 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="locale.conf"> + <refentryinfo> + <title>locale.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>locale.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>locale.conf</refname> + <refpurpose>Configuration file for locale settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/locale.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/locale.conf</filename> file configures + system-wide locale settings. It is read at early boot by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>The basic file format of <filename>locale.conf</filename> is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments, no + shell features are supported, allowing applications to read the + file without implementing a shell compatible execution + engine.</para> + + <para>Note that the kernel command line options + <varname>locale.LANG=</varname>, + <varname>locale.LANGUAGE=</varname>, + <varname>locale.LC_CTYPE=</varname>, + <varname>locale.LC_NUMERIC=</varname>, + <varname>locale.LC_TIME=</varname>, + <varname>locale.LC_COLLATE=</varname>, + <varname>locale.LC_MONETARY=</varname>, + <varname>locale.LC_MESSAGES=</varname>, + <varname>locale.LC_PAPER=</varname>, + <varname>locale.LC_NAME=</varname>, + <varname>locale.LC_ADDRESS=</varname>, + <varname>locale.LC_TELEPHONE=</varname>, + <varname>locale.LC_MEASUREMENT=</varname>, + <varname>locale.LC_IDENTIFICATION=</varname> may be + used to override the locale settings at boot.</para> + + <para>The locale settings configured in + <filename>/etc/locale.conf</filename> are system-wide and are + inherited by every service or user, unless overridden or unset by + individual programs or individual users.</para> + + <para>Depending on the operating system, other configuration files + might be checked for locale configuration as well, however only as + fallback.</para> + + <para><citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be used to alter the settings in this file during runtime from + the command line. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize them on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following locale settings may be set using + <filename>/etc/locale.conf</filename>: + <varname>LANG=</varname>, + <varname>LANGUAGE=</varname>, + <varname>LC_CTYPE=</varname>, + <varname>LC_NUMERIC=</varname>, + <varname>LC_TIME=</varname>, + <varname>LC_COLLATE=</varname>, + <varname>LC_MONETARY=</varname>, + <varname>LC_MESSAGES=</varname>, + <varname>LC_PAPER=</varname>, + <varname>LC_NAME=</varname>, + <varname>LC_ADDRESS=</varname>, + <varname>LC_TELEPHONE=</varname>, + <varname>LC_MEASUREMENT=</varname>, + <varname>LC_IDENTIFICATION=</varname>. + Note that <varname>LC_ALL</varname> may not be configured in this + file. For details about the meaning and semantics of these + settings, refer to + <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German locale with English messages</title> + + <para><filename>/etc/locale.conf</filename>:</para> + + <programlisting>LANG=de_DE.UTF-8 +LC_MESSAGES=en_US.UTF-8</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/localtime.xml b/src/manpages/localtime.xml new file mode 100644 index 0000000000..2827da6e93 --- /dev/null +++ b/src/manpages/localtime.xml @@ -0,0 +1,103 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + Copyright 2012 Shawn Landden + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="localtime"> + <refentryinfo> + <title>localtime</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Shawn</firstname> + <surname>Landden</surname> + <email>shawnlandden@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>localtime</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>localtime</refname> + <refpurpose>Local timezone configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/localtime</filename> -> <filename>../usr/share/zoneinfo/…</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/localtime</filename> file configures the + system-wide timezone of the local system that is used by + applications for presentation to the user. It should be an + absolute or relative symbolic link pointing to + <filename>/usr/share/zoneinfo/</filename>, followed by a timezone + identifier such as <literal>Europe/Berlin</literal> or + <literal>Etc/UTC</literal>. The resulting link should lead to the + corresponding binary + <citerefentry project='man-pages'><refentrytitle>tzfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> + timezone data for the configured timezone.</para> + + <para>Because the timezone identifier is extracted from the + symlink target name of <filename>/etc/localtime</filename>, this + file may not be a normal file or hardlink.</para> + + <para>The timezone may be overridden for individual programs by + using the <varname>$TZ</varname> environment variable. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>You may use + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line during + runtime. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the time zone on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/logind.conf.xml b/src/manpages/logind.conf.xml new file mode 100644 index 0000000000..fe92277a1f --- /dev/null +++ b/src/manpages/logind.conf.xml @@ -0,0 +1,349 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="logind.conf" conditional='ENABLE_LOGIND' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>logind.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>logind.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>logind.conf</refname> + <refname>logind.conf.d</refname> + <refpurpose>Login manager configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/logind.conf</filename></para> + <para><filename>/etc/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/logind.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd + login manager, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Login]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAutoVTs=</varname></term> + + <listitem><para>Takes a positive integer. Configures how many + virtual terminals (VTs) to allocate by default that, when + switched to and are previously unused, + <literal>autovt</literal> services are automatically spawned + on. These services are instantiated from the template unit + <filename>autovt@.service</filename> for the respective VT TTY + name, for example, <filename>autovt@tty4.service</filename>. + By default, <filename>autovt@.service</filename> is linked to + <filename>getty@.service</filename>. In other words, login + prompts are started dynamically as the user switches to unused + virtual terminals. Hence, this parameter controls how many + login <literal>gettys</literal> are available on the VTs. If a + VT is already used by some other subsystem (for example, a + graphical login), this kind of activation will not be + attempted. Note that the VT configured in + <varname>ReserveVT=</varname> is always subject to this kind + of activation, even if it is not one of the VTs configured + with the <varname>NAutoVTs=</varname> directive. Defaults to + 6. When set to 0, automatic spawning of + <literal>autovt</literal> services is + disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReserveVT=</varname></term> + + <listitem><para>Takes a positive integer. Identifies one + virtual terminal that shall unconditionally be reserved for + <filename>autovt@.service</filename> activation (see above). + The VT selected with this option will be marked busy + unconditionally, so that no other subsystem will allocate it. + This functionality is useful to ensure that, regardless of how + many VTs are allocated by other subsystems, one login + <literal>getty</literal> is always available. Defaults to 6 + (in other words, there will always be a + <literal>getty</literal> available on Alt-F6.). When set to 0, + VT reservation is disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillUserProcesses=</varname></term> + + <listitem><para>Takes a boolean argument. Configures whether the processes of a + user should be killed when the user logs out. If true, the scope unit + corresponding to the session and all processes inside that scope will be + terminated. If false, the scope is "abandoned", see + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and processes are not killed. Defaults to <literal>yes</literal>, + but see the options <varname>KillOnlyUsers=</varname> and + <varname>KillExcludeUsers=</varname> below.</para> + + <para>In addition to session processes, user process may run under the user + manager unit <filename>user@.service</filename>. Depending on the linger + settings, this may allow users to run processes independent of their login + sessions. See the description of <command>enable-linger</command> in + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <para>Note that setting <varname>KillUserProcesses=yes</varname> + will break tools like + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + unless they are moved out of the session scope. See example in + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillOnlyUsers=</varname></term> + <term><varname>KillExcludeUsers=</varname></term> + + <listitem><para>These settings take space-separated lists of usernames that override + the <varname>KillUserProcesses=</varname> setting. A user name may be added to + <varname>KillExcludeUsers=</varname> to exclude the processes in the session scopes of + that user from being killed even if <varname>KillUserProcesses=yes</varname> is set. If + <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user is + excluded by default. <varname>KillExcludeUsers=</varname> may be set to an empty value + to override this default. If a user is not excluded, <varname>KillOnlyUsers=</varname> + is checked next. If this setting is specified, only the session scopes of those users + will be killed. Otherwise, users are subject to the + <varname>KillUserProcesses=yes</varname> setting.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IdleAction=</varname></term> + + <listitem><para>Configures the action to take when the system + is idle. Takes one of + <literal>ignore</literal>, + <literal>poweroff</literal>, + <literal>reboot</literal>, + <literal>halt</literal>, + <literal>kexec</literal>, + <literal>suspend</literal>, + <literal>hibernate</literal>, + <literal>hybrid-sleep</literal>, and + <literal>lock</literal>. + Defaults to <literal>ignore</literal>.</para> + + <para>Note that this requires that user sessions correctly + report the idle status to the system. The system will execute + the action after all sessions report that they are idle, no + idle inhibitor lock is active, and subsequently, the time + configured with <varname>IdleActionSec=</varname> (see below) + has expired.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IdleActionSec=</varname></term> + + <listitem><para>Configures the delay after which the action + configured in <varname>IdleAction=</varname> (see above) is + taken after the system is idle.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>InhibitDelayMaxSec=</varname></term> + + <listitem><para>Specifies the maximum time a system shutdown + or sleep request is delayed due to an inhibitor lock of type + <literal>delay</literal> being active before the inhibitor is + ignored and the operation executes anyway. Defaults to + 5.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HandlePowerKey=</varname></term> + <term><varname>HandleSuspendKey=</varname></term> + <term><varname>HandleHibernateKey=</varname></term> + <term><varname>HandleLidSwitch=</varname></term> + <term><varname>HandleLidSwitchDocked=</varname></term> + + <listitem><para>Controls whether logind shall handle the + system power and sleep keys and the lid switch to trigger + actions such as system power-off or suspend. Can be one of + <literal>ignore</literal>, + <literal>poweroff</literal>, + <literal>reboot</literal>, + <literal>halt</literal>, + <literal>kexec</literal>, + <literal>suspend</literal>, + <literal>hibernate</literal>, + <literal>hybrid-sleep</literal>, and + <literal>lock</literal>. + If <literal>ignore</literal>, logind will never handle these + keys. If <literal>lock</literal>, all running sessions will be + screen-locked; otherwise, the specified action will be taken + in the respective event. Only input devices with the + <literal>power-switch</literal> udev tag will be watched for + key/lid switch events. <varname>HandlePowerKey=</varname> + defaults to <literal>poweroff</literal>. + <varname>HandleSuspendKey=</varname> and + <varname>HandleLidSwitch=</varname> default to + <literal>suspend</literal>. + <varname>HandleLidSwitchDocked=</varname> defaults to + <literal>ignore</literal>. + <varname>HandleHibernateKey=</varname> defaults to + <literal>hibernate</literal>. If the system is inserted in a + docking station, or if more than one display is connected, the + action specified by <varname>HandleLidSwitchDocked=</varname> + occurs; otherwise the <varname>HandleLidSwitch=</varname> + action occurs.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PowerKeyIgnoreInhibited=</varname></term> + <term><varname>SuspendKeyIgnoreInhibited=</varname></term> + <term><varname>HibernateKeyIgnoreInhibited=</varname></term> + <term><varname>LidSwitchIgnoreInhibited=</varname></term> + + <listitem><para>Controls whether actions triggered by the + power and sleep keys and the lid switch are subject to + inhibitor locks. These settings take boolean arguments. If + <literal>no</literal>, the inhibitor locks taken by + applications in order to block the requested operation are + respected. If <literal>yes</literal>, the requested operation + is executed in any case. + <varname>PowerKeyIgnoreInhibited=</varname>, + <varname>SuspendKeyIgnoreInhibited=</varname> and + <varname>HibernateKeyIgnoreInhibited=</varname> default to + <literal>no</literal>. + <varname>LidSwitchIgnoreInhibited=</varname> defaults to + <literal>yes</literal>. This means that the lid switch does + not respect suspend blockers by default, but the power and + sleep keys do. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HoldoffTimeoutSec=</varname></term> + + <listitem><para>Specifies the timeout after system startup or + system resume in which systemd will hold off on reacting to + lid events. This is required for the system to properly + detect any hotplugged devices so systemd can ignore lid events + if external monitors, or docks, are connected. If set to 0, + systemd will always react immediately, possibly before the + kernel fully probed all hotplugged devices. This is safe, as + long as you do not care for systemd to account for devices + that have been plugged or unplugged while the system was off. + Defaults to 30s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeDirectorySize=</varname></term> + + <listitem><para>Sets the size limit on the + <varname>$XDG_RUNTIME_DIR</varname> runtime directory for each + user who logs in. Takes a size in bytes, optionally suffixed + with the usual K, G, M, and T suffixes, to the base 1024 + (IEC). Alternatively, a numerical percentage suffixed by + <literal>%</literal> may be specified, which sets the size + limit relative to the amount of physical RAM. Defaults to 10%. + Note that this size is a safety limit only. As each runtime + directory is a tmpfs file system, it will only consume as much + memory as is needed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>InhibitorsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 + (8K).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SessionsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 + (8K). Depending on how the <filename>pam_systemd.so</filename> module is included in the PAM stack + configuration, further login sessions will either be refused, or permitted but not tracked by + <filename>systemd-logind</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UserTasksMax=</varname></term> + + <listitem><para>Sets the maximum number of OS tasks each user + may run concurrently. This controls the + <varname>TasksMax=</varname> setting of the per-user slice + unit, see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Defaults to 12288 (12K).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the + user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the + last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as + well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users + are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/machine-id.xml b/src/manpages/machine-id.xml new file mode 100644 index 0000000000..d318ec54ec --- /dev/null +++ b/src/manpages/machine-id.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-id"> + <refentryinfo> + <title>machine-id</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-id</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-id</refname> + <refpurpose>Local machine ID configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-id</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-id</filename> file contains the + unique machine ID of the local system that is set during + installation. The machine ID is a single newline-terminated, + hexadecimal, 32-character, lowercase machine ID string. When + decoded from hexadecimal, this corresponds with a 16-byte/128-bit + string.</para> + + <para>The machine ID is usually generated from a random source + during system installation and stays constant for all subsequent + boots. Optionally, for stateless systems, it is generated during + runtime at early boot if it is found to be empty.</para> + + <para>The machine ID does not change based on user configuration + or when hardware is replaced.</para> + + <para>This machine ID adheres to the same format and logic as the + D-Bus machine ID.</para> + + <para>Programs may use this ID to identify the host with a + globally unique ID in the network, which does not change even if + the local network configuration changes. Due to this and its + greater length, it is a more useful replacement for the + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call that POSIX specifies.</para> + + <para>The + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool may be used by installer tools to initialize the machine ID + at install time. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + + <para>The machine-id may also be set, for example when network + booting, by setting the <varname>systemd.machine_id=</varname> + kernel command line parameter or passing the option + <option>--machine-id=</option> to systemd. A machine-id may not + be set to all zeros.</para> + </refsect1> + + <refsect1> + <title>Relation to OSF UUIDs</title> + + <para>Note that the machine ID historically is not an OSF UUID as + defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, nor a Microsoft GUID; however, starting with systemd + v30, newly generated machine IDs do qualify as v4 UUIDs.</para> + + <para>In order to maintain compatibility with existing + installations, an application requiring a UUID should decode the + machine ID, and then apply the following operations to turn it + into a valid OSF v4 UUID. With <literal>id</literal> being an + unsigned character array:</para> + + <programlisting>/* Set UUID version to 4 --- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80;</programlisting> + + <para>(This code is inspired by + <literal>generate_random_uuid()</literal> of + <filename>drivers/char/random.c</filename> from the Linux kernel + sources.)</para> + + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/machine-id</filename> originates in the + <filename>/var/lib/dbus/machine-id</filename> file introduced by + D-Bus. In fact, this latter file might be a symlink to + <filename>/etc/machine-id</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/machine-info.xml b/src/manpages/machine-info.xml new file mode 100644 index 0000000000..351133670b --- /dev/null +++ b/src/manpages/machine-info.xml @@ -0,0 +1,185 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-info"> + <refentryinfo> + <title>machine-info</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-info</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-info</refname> + <refpurpose>Local machine information file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-info</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-info</filename> file contains + machine metadata.</para> + + <para>The basic file format of <filename>machine-info</filename> + is a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments no + shell features are supported, allowing applications to read the + file without implementing a shell compatible execution + engine.</para> + + <para><filename>/etc/machine-info</filename> contains metadata + about the machine that is set by the user or administrator.</para> + + <para>Depending on the operating system other configuration files + might be checked for machine information as well, however only as + fallback.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following machine metadata parameters may be set using + <filename>/etc/machine-info</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>PRETTY_HOSTNAME=</varname></term> + + <listitem><para>A pretty human-readable UTF-8 machine + identifier string. This should contain a name like + <literal>Lennart's Laptop</literal> which is useful to present + to the user and does not suffer by the syntax limitations of + internet domain names. If possible, the internet hostname as + configured in <filename>/etc/hostname</filename> should be + kept similar to this one. Example: if this value is + <literal>Lennart's Computer</literal> an Internet hostname of + <literal>lennarts-computer</literal> might be a good choice. + If this parameter is not set, an application should fall back + to the Internet host name for presentation + purposes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ICON_NAME=</varname></term> + + <listitem><para>An icon identifying this machine according to + the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming Specification</ulink>. If this parameter is not + set, an application should fall back to + <literal>computer</literal> or a similar icon + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CHASSIS=</varname></term> + + <listitem><para>The chassis type. Currently, the following + chassis types are defined: + <literal>desktop</literal>, + <literal>laptop</literal>, + <literal>server</literal>, + <literal>tablet</literal>, + <literal>handset</literal>, + <literal>watch</literal>, and + <literal>embedded</literal>, + as well as the special chassis types + <literal>vm</literal> and + <literal>container</literal> for + virtualized systems that lack an immediate physical chassis. + Note that many systems allow detection of the chassis type + automatically (based on firmware information or suchlike). + This setting (if set) shall take precedence over automatically + detected information and is useful to override misdetected + configuration or to manually configure the chassis type where + automatic detection is not available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DEPLOYMENT=</varname></term> + + <listitem><para>Describes the system deployment environment. + One of the following is suggested: + <literal>development</literal>, + <literal>integration</literal>, + <literal>staging</literal>, + <literal>production</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LOCATION=</varname></term> + + <listitem><para>Describes the system location if applicable + and known. Takes a human-friendly, free-form string. This may + be as generic as <literal>Berlin, Germany</literal> or as + specific as <literal>Left Rack, 2nd Shelf</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>PRETTY_HOSTNAME="Lennart's Tablet" +ICON_NAME=computer-tablet +CHASSIS=tablet +DEPLOYMENT=production</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/modules-load.d.xml b/src/manpages/modules-load.d.xml new file mode 100644 index 0000000000..4b722aa128 --- /dev/null +++ b/src/manpages/modules-load.d.xml @@ -0,0 +1,101 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="modules-load.d" conditional='HAVE_KMOD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>modules-load.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>modules-load.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>modules-load.d</refname> + <refpurpose>Configure kernel modules to load at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/modules-load.d/*.conf</filename></para> + <para><filename>/run/modules-load.d/*.conf</filename></para> + <para><filename>/usr/lib/modules-load.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads files from the above directories which contain kernel + modules to load during boot in a static list. Each configuration + file is named in the style of + <filename>/etc/modules-load.d/<replaceable>program</replaceable>.conf</filename>. + Note that it is usually a better idea to rely on the automatic + module loading by PCI IDs, USB IDs, DMI IDs or similar triggers + encoded in the kernel modules themselves instead of static + configuration like this. In fact, most modern kernel modules are + prepared for automatic loading already.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files should simply contain a list of + kernel module names to load, separated by newlines. Empty lines + and lines whose first non-whitespace character is # or ; are + ignored.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/modules-load.d/virtio-net.conf example:</title> + + <programlisting># Load virtio-net.ko at boot +virtio-net</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/networkd.conf.xml b/src/manpages/networkd.conf.xml new file mode 100644 index 0000000000..4bfc4f773a --- /dev/null +++ b/src/manpages/networkd.conf.xml @@ -0,0 +1,154 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Vinay Kulkarni + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="networkd.conf" conditional='ENABLE_NETWORKD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>networkd.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Vinay</firstname> + <surname>Kulkarni</surname> + <email>kulkarniv@vmware.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>networkd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>networkd.conf</refname> + <refname>networkd.conf.d</refname> + <refpurpose>Global Network configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/networkd.conf</filename></para> + <para><filename>/etc/systemd/networkd.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/networkd.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control global network parameters. + Currently the DHCP Unique Identifier (DUID).</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>[DHCP] Section Options</title> + + <para>This section configures the DHCP Unique Identifier (DUID) value used by DHCP + protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface + Identity Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 + address. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring + a dynamic IPv4 address if <option>ClientIdentifier=duid</option>. IAID and DUID allows + a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP. + To configure IAID and ClientIdentifier, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>The following options are understood:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem><para>Specifies how the DUID should be generated. See + <ulink url="https://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink> + for a description of all the options.</para> + + <para>The following values are understood: + <variablelist> + <varlistentry> + <term><option>vendor</option> </term> + <listitem><para>If <literal>DUIDType=vendor</literal>, then the DUID value will be generated using + <literal>43793</literal> as the vendor identifier (systemd) and hashed contents of + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + This is the default if <varname>DUIDType=</varname> is not specified. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>link-layer-time</option> </term> + <term><option>link-layer</option> </term> + <term><option>uuid</option> </term> + <listitem><para>Those values are parsed and can be used to set the DUID type + field, but DUID contents must be provided using <varname>DUIDRawData=</varname>. + </para></listitem> + </varlistentry> + </variablelist> + </para> + + <para>In all cases, <varname>DUIDRawData=</varname> can be used to override the + actual DUID value that is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem><para>Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each + byte separated by <literal>:</literal>. The DUID that is sent is composed of the DUID type specified by + <varname>DUIDType=</varname> and the value configured here.</para> + + <para>The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id + from the <filename>/etc/machine-id</filename> file. To configure DUID per-network, see + <citerefentry><refentrytitle>systemd.network </refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The configured DHCP DUID should conform to the specification in + <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>, + <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>. To configure IAID, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>.</para> + + <example> + <title>A <option>DUIDType=vendor</option> with a custom value</title> + + <programlisting>DUIDType=vendor +DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting> + + <para>This specifies a 14 byte DUID, with the type DUID-EN (<literal>00:02</literal>), enterprise number + 43793 (<literal>00:00:ab:11</literal>), and identifier value <literal>f9:2a:c2:77:29:f9:5c:00</literal>. + </para> + </example> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/os-release.xml b/src/manpages/os-release.xml new file mode 100644 index 0000000000..a70ba1aa31 --- /dev/null +++ b/src/manpages/os-release.xml @@ -0,0 +1,362 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="os-release"> + <refentryinfo> + <title>os-release</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>os-release</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>os-release</refname> + <refpurpose>Operating system identification</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/os-release</filename></para> + <para><filename>/usr/lib/os-release</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files contain operating + system identification data.</para> + + <para>The basic file format of <filename>os-release</filename> is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments, no + shell features are supported (this means variable expansion is + explicitly not supported), allowing applications to read the file + without implementing a shell compatible execution engine. Variable + assignment values must be enclosed in double or single quotes if + they include spaces, semicolons or other special characters + outside of A–Z, a–z, 0–9. Shell special characters ("$", quotes, + backslash, backtick) must be escaped with backslashes, following + shell style. All strings should be in UTF-8 format, and + non-printable characters should not be used. It is not supported + to concatenate multiple individually quoted strings. Lines + beginning with "#" shall be ignored as comments.</para> + + <para>The file <filename>/etc/os-release</filename> takes + precedence over <filename>/usr/lib/os-release</filename>. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + <filename>/usr/lib/os-release</filename> if it is missing. + Applications should not read data from both files at the same + time. <filename>/usr/lib/os-release</filename> is the recommended + place to store OS release information as part of vendor trees. + <filename>/etc/os-release</filename> should be a relative symlink + to <filename>/usr/lib/os-release</filename>, to provide + compatibility with applications only looking at + <filename>/etc</filename>. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut.</para> + + <para><filename>os-release</filename> contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator.</para> + + <para>As this file only encodes names and identifiers it should + not be localized.</para> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files might be symlinks + to other files, but it is important that the file is available + from earliest boot on, and hence must be located on the root file + system.</para> + + <para>For a longer rationale for <filename>os-release</filename> + please refer to the <ulink + url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following OS identifications parameters may be set using + <filename>os-release</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAME=</varname></term> + + <listitem><para>A string identifying the operating system, + without a version component, and suitable for presentation to + the user. If not set, defaults to + <literal>NAME=GNU/Linux</literal>. Example: + <literal>NAME=BLAG</literal> or <literal>NAME="gNewSense + GNU/Linux"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION=</varname></term> + + <listitem><para>A string identifying the operating system + version, excluding any OS name information, possibly including + a release code name, and suitable for presentation to the + user. This field is optional. Example: + <literal>VERSION=210k</literal> or <literal>VERSION="210k + (Spartakus)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID=</varname></term> + + <listitem><para>A lower-case string (no spaces or other + characters outside of 0–9, a–z, ".", "_" and "-") identifying + the operating system, excluding any version information and + suitable for processing by scripts or usage in generated + filenames. If not set, defaults to + <literal>ID=gnu-linux</literal>. Example: + <literal>ID=blag</literal> or + <literal>ID=gnewsense</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_LIKE=</varname></term> + + <listitem><para>A space-separated list of operating system + identifiers in the same syntax as the <varname>ID=</varname> + setting. It should list identifiers of operating systems that + are closely related to the local operating system in regards + to packaging and programming interfaces, for example listing + one or more OS identifiers the local OS is a derivative from. + An OS should generally only list other OS identifiers it + itself is a derivative of, and not any OSes that are derived + from it, though symmetric relationships are possible. Build + scripts and similar should check this variable if they need to + identify the local operating system and the value of + <varname>ID=</varname> is not recognized. Operating systems + should be listed in order of how closely the local operating + system relates to the listed ones, starting with the closest. + This field is optional. Example: for an operating system with + <literal>ID=blag</literal>, an assignment of + <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. + For an operating system with <literal>ID=gnewsense</literal>, an + assignment of <literal>ID_LIKE=debian</literal> is + appropriate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION_ID=</varname></term> + + <listitem><para>A lower-case string (mostly numeric, no spaces + or other characters outside of 0–9, a–z, ".", "_" and "-") + identifying the operating system version, excluding any OS + name information or release code name, and suitable for + processing by scripts or usage in generated filenames. This + field is optional. Example: <literal>VERSION_ID=210k</literal> + or <literal>VERSION_ID=7.0</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRETTY_NAME=</varname></term> + + <listitem><para>A pretty operating system name in a format + suitable for presentation to the user. May or may not contain + a release code name or OS version of some kind, as suitable. + If not set, defaults to + <literal>PRETTY_NAME="GNU/Linux"</literal>. Example: + <literal>PRETTY_NAME="BLAG 210k + (Spartakus)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ANSI_COLOR=</varname></term> + + <listitem><para>A suggested presentation color when showing + the OS name on the console. This should be specified as string + suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code + for setting graphical rendition. This field is optional. + Example: <literal>ANSI_COLOR="0;31"</literal> for red, or + <literal>ANSI_COLOR="1;34"</literal> for light + blue.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPE_NAME=</varname></term> + + <listitem><para>A CPE name for the operating system, in URI + binding syntax, following the + <ulink url="http://scap.nist.gov/specifications/cpe/">Common + Platform Enumeration Specification</ulink> as proposed by the + NIST. This field is optional. Example: + <literal>CPE_NAME="cpe:/o:blagblagblag:blag:210k"</literal> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HOME_URL=</varname></term> + <term><varname>SUPPORT_URL=</varname></term> + <term><varname>BUG_REPORT_URL=</varname></term> + <term><varname>PRIVACY_POLICY_URL=</varname></term> + + <listitem><para>Links to resources on the Internet related the + operating system. <varname>HOME_URL=</varname> should refer to + the homepage of the operating system, or alternatively some + homepage of the specific version of the operating system. + <varname>SUPPORT_URL=</varname> should refer to the main + support page for the operating system, if there is any. This + is primarily intended for operating systems which vendors + provide support for. <varname>BUG_REPORT_URL=</varname> should + refer to the main bug reporting page for the operating system, + if there is any. This is primarily intended for operating + systems that rely on community QA. + <varname>PRIVACY_POLICY_URL=</varname> should refer to the + main privacy policy page for the operation system, if there is + any. These settings are optional, and providing only some of + these settings is common. These URLs are intended to be + exposed in "About this system" UIs behind links with captions + such as "About this Operating System", "Obtain Support", + "Report a Bug", or "Privacy Policy". The values should be in + <ulink url="https://tools.ietf.org/html/rfc3986">RFC3986 + format</ulink>, and should be <literal>http:</literal> or + <literal>https:</literal> URLs, and possibly + <literal>mailto:</literal> or <literal>tel:</literal>. Only + one URL shall be listed in each setting. If multiple resources + need to be referenced, it is recommended to provide an online + landing page linking all available resources. Examples: + <literal>HOME_URL="https://www.blagblagblag.org/"</literal> and + <literal>BUG_REPORT_URL="https://blag.fsf.org/"</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BUILD_ID=</varname></term> + + <listitem><para>A string uniquely identifying the system image + used as the origin for a distribution (it is not updated with + system updates). The field can be identical between different + VERSION_IDs as BUILD_ID is an only a unique identifier to a + specific version. Distributions that release each update as a + new version would only need to use VERSION_ID as each build is + already distinct based on the VERSION_ID. This field is + optional. Example: <literal>BUILD_ID="2013-03-20.3"</literal> + or <literal>BUILD_ID=201303203</literal>. + + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VARIANT=</varname></term> + + <listitem><para> + A string identifying a specific variant or edition of the + operating system suitable for presentation to the user. This + field may be used to inform the user that the configuration of + this system is subject to a specific divergent set of rules or + default configuration settings. This field is optional and may + not be implemented on all systems. + Examples: + <literal>VARIANT="Server Edition"</literal>, + <literal>VARIANT="Smart Refrigerator Edition"</literal> + Note: this field is for display purposes only. The + <varname>VARIANT_ID</varname> field should be used for making + programmatic decisions. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VARIANT_ID=</varname></term> + + <listitem><para> + A lower-case string (no spaces or other characters outside of + 0–9, a–z, ".", "_" and "-"), identifying a specific variant or + edition of the operating system. This may be interpreted by + other packages in order to determine a divergent default + configuration. This field is optional and may not be + implemented on all systems. + Examples: + <literal>VARIANT_ID=server</literal>, + <literal>VARIANT_ID=embedded</literal> + </para></listitem> + </varlistentry> + + </variablelist> + + <para>If you are reading this file from C code or a shell script + to determine the OS or a specific version of it, use the + <varname>ID</varname> and <varname>VERSION_ID</varname> fields, + possibly with <varname>ID_LIKE</varname> as fallback for + <varname>ID</varname>. When looking for an OS identification + string for presentation to the user use the + <varname>PRETTY_NAME</varname> field.</para> + + <para>Note that operating system vendors may choose not to provide + version information, for example to accommodate for rolling + releases. In this case, <varname>VERSION</varname> and + <varname>VERSION_ID</varname> may be unset. Applications should + not rely on these fields to be set.</para> + + <para>Operating system vendors may extend the file + format and introduce new fields. It is highly + recommended to prefix new fields with an OS specific + name in order to avoid name clashes. Applications + reading this file must ignore unknown fields. Example: + <literal>DEBIAN_BTS="debbugs://bugs.gnewsense.org/"</literal></para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>NAME=Parabola +VERSION="rolling-release" +ID=parabola +ID_LIKE=arch +VERSION_ID=rolling-release +PRETTY_NAME="Parabola GNU/Linux-libre" +ANSI_COLOR="1;35" +CPE_NAME="cpe:/o:parabola:parabola:rolling-release" +HOME_URL="https://www.parabola.nu/" +BUG_REPORT_URL="https://labs.parabola.nu/"</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/resolved.conf.xml b/src/manpages/resolved.conf.xml new file mode 100644 index 0000000000..920ce9e89b --- /dev/null +++ b/src/manpages/resolved.conf.xml @@ -0,0 +1,219 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="resolved.conf" conditional='ENABLE_RESOLVED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>resolved.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>resolved.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>resolved.conf</refname> + <refname>resolved.conf.d</refname> + <refpurpose>Network Name Resolution configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/resolved.conf</filename></para> + <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control local DNS and LLMNR + name resolution.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>The following options are available in the <literal>[Resolve]</literal> section:</para> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>DNS=</varname></term> + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests + are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or + set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS + servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers + are configured in it. This setting defaults to the empty list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FallbackDNS=</varname></term> + <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any + per-link DNS servers obtained from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or + <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is + known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Domains=</varname></term> + <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving + single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified + domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name + with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search + domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains + are configured in it. This setting defaults to the empty list.</para> + + <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not + define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured + with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers + are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the + construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and + <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the + system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LLMNR=</varname></term> + <listitem><para>Takes a boolean argument or + <literal>resolve</literal>. Controls Link-Local Multicast Name + Resolution support (<ulink + url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on + the local host. If true, enables full LLMNR responder and + resolver support. If false, disables both. If set to + <literal>resolve</literal>, only resolution support is enabled, + but responding is disabled. Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also maintains per-link LLMNR settings. LLMNR will be + enabled on a link only if the per-link and the + global setting is on.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem><para>Takes a boolean argument or + <literal>allow-downgrade</literal>. If true all DNS lookups are + DNSSEC-validated locally (excluding LLMNR and Multicast + DNS). If the response to a lookup request is detected to be invalid + a lookup failure is returned to applications. Note that + this mode requires a DNS server that supports DNSSEC. If the + DNS server does not properly support DNSSEC all validations + will fail. If set to <literal>allow-downgrade</literal> DNSSEC + validation is attempted, but if the server does not support + DNSSEC properly, DNSSEC mode is automatically disabled. Note + that this mode makes DNSSEC validation vulnerable to + "downgrade" attacks, where an attacker might be able to + trigger a downgrade to non-DNSSEC mode by synthesizing a DNS + response that suggests DNSSEC was not supported. If set to + false, DNS lookups are not DNSSEC validated.</para> + + <para>Note that DNSSEC validation requires retrieval of + additional DNS data, and thus results in a small DNS look-up + time penalty.</para> + + <para>DNSSEC requires knowledge of "trust anchors" to prove + data integrity. The trust anchor for the Internet root domain + is built into the resolver, additional trust anchors may be + defined with + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Trust anchors may change at regular intervals, and old trust + anchors may be revoked. In such a case DNSSEC validation is + not possible until new trust anchors are configured locally or + the resolver software package is updated with the new root + trust anchor. In effect, when the built-in trust anchor is + revoked and <varname>DNSSEC=</varname> is true, all further + lookups will fail, as it cannot be proved anymore whether + lookups are correctly signed, or validly unsigned. If + <varname>DNSSEC=</varname> is set to + <literal>allow-downgrade</literal> the resolver will + automatically turn off DNSSEC validation in such a case.</para> + + <para>Client programs looking up DNS data will be informed + whether lookups could be verified using DNSSEC, or whether the + returned data could not be verified (either because the data + was found unsigned in the DNS, or the DNS server did not + support DNSSEC or no appropriate trust anchors were known). In + the latter case it is assumed that client programs employ a + secondary scheme to validate the returned DNS data, should + this be required.</para> + + <para>It is recommended to set <varname>DNSSEC=</varname> to + true on systems where it is known that the DNS server supports + DNSSEC correctly, and where software or trust anchor updates + happen regularly. On other systems it is recommended to set + <varname>DNSSEC=</varname> to + <literal>allow-downgrade</literal>.</para> + + <para>In addition to this global DNSSEC setting + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also maintains per-link DNSSEC settings. For system DNS + servers (see above), only the global DNSSEC setting is in + effect. For per-link DNS servers the per-link + setting is in effect, unless it is unset in which case the + global setting is used instead.</para> + + <para>Site-private DNS zones generally conflict with DNSSEC + operation, unless a negative (if the private zone is not + signed) or positive (if the private zone is signed) trust + anchor is configured for them. If + <literal>allow-downgrade</literal> mode is selected, it is + attempted to detect site-private DNS zones using top-level + domains (TLDs) that are not known by the DNS root server. This + logic does not work in all private zone setups.</para> + + <para>Defaults to off.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/runlevel.xml b/src/manpages/runlevel.xml new file mode 100644 index 0000000000..ca29c7c22c --- /dev/null +++ b/src/manpages/runlevel.xml @@ -0,0 +1,192 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="runlevel" + xmlns:xi="http://www.w3.org/2001/XInclude" + conditional="HAVE_UTMP"> + + <refentryinfo> + <title>runlevel</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>runlevel</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>runlevel</refname> + <refpurpose>Print previous and current SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>runlevel</command> + <arg choice="opt" rep="repeat">options</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Overview</title> + + <para>"Runlevels" are an obsolete way to start and stop groups of + services used in SysV init. systemd provides a compatibility layer + that maps runlevels to targets, and associated binaries like + <command>runlevel</command>. Nevertheless, only one runlevel can + be "active" at a given time, while systemd can activate multiple + targets concurrently, so the mapping to runlevels is confusing + and only approximate. Runlevels should not be used in new code, + and are mostly useful as a shorthand way to refer the matching + systemd targets in kernel boot parameters.</para> + + <table> + <title>Mapping between runlevels and systemd targets</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="runlevel" /> + <colspec colname="target" /> + <thead> + <row> + <entry>Runlevel</entry> + <entry>Target</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry><filename>poweroff.target</filename></entry> + </row> + <row> + <entry>1</entry> + <entry><filename>rescue.target</filename></entry> + </row> + <row> + <entry>2, 3, 4</entry> + <entry><filename>multi-user.target</filename></entry> + </row> + <row> + <entry>5</entry> + <entry><filename>graphical.target</filename></entry> + </row> + <row> + <entry>6</entry> + <entry><filename>reboot.target</filename></entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>Description</title> + + <para><command>runlevel</command> prints the previous and current + SysV runlevel if they are known.</para> + + <para>The two runlevel characters are separated by a single space + character. If a runlevel cannot be determined, N is printed + instead. If neither can be determined, the word "unknown" is + printed.</para> + + <para>Unless overridden in the environment, this will check the + utmp database for recent runlevel changes.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following option is understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>If one or both runlevels could be determined, 0 is returned, + a non-zero failure code otherwise.</para> + + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$RUNLEVEL</varname></term> + + <listitem><para>If <varname>$RUNLEVEL</varname> is set, + <command>runlevel</command> will print this value as current + runlevel and ignore utmp.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$PREVLEVEL</varname></term> + + <listitem><para>If <varname>$PREVLEVEL</varname> is set, + <command>runlevel</command> will print this value as previous + runlevel and ignore utmp.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + <varlistentry> + <term><filename>/var/run/utmp</filename></term> + + <listitem><para>The utmp database <command>runlevel</command> + reads the previous and current runlevel + from.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/shutdown.xml b/src/manpages/shutdown.xml new file mode 100644 index 0000000000..a8af387c67 --- /dev/null +++ b/src/manpages/shutdown.xml @@ -0,0 +1,175 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="shutdown" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>shutdown</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>shutdown</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>shutdown</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>shutdown</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt">TIME</arg> + <arg choice="opt" rep="repeat">WALL</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>shutdown</command> may be used to halt, power-off + or reboot the machine.</para> + + <para>The first argument may be a time string (which is usually + <literal>now</literal>). Optionally, this may be followed by a + wall message to be sent to all logged-in users before going + down.</para> + + <para>The time string may either be in the format + <literal>hh:mm</literal> for hour/minutes specifying the time to + execute the shutdown at, specified in 24h clock format. + Alternatively it may be in the syntax <literal>+m</literal> + referring to the specified number of minutes m from now. + <literal>now</literal> is an alias for <literal>+0</literal>, i.e. + for triggering an immediate shutdown. If no time argument is + specified, <literal>+1</literal> is implied.</para> + + <para>Note that to specify a wall message you must specify a time + argument, too.</para> + + <para>If the time argument is used, 5 minutes before the system + goes down the <filename>/run/nologin</filename> file is created to + ensure that further logins shall not be allowed.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the machine (the + default).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the + machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option></term> + + <listitem><para>Equivalent to <option>--poweroff</option>, + unless <option>--halt</option> is specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Do not halt, power-off, reboot, just write + wall message.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall + message before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem><para>Cancel a pending shutdown. This may be used + cancel the effect of an invocation of + <command>shutdown</command> with a time argument that is not + <literal>+0</literal> or + <literal>now</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/standard-conf.xml b/src/manpages/standard-conf.xml new file mode 100644 index 0000000000..6edbb7ff83 --- /dev/null +++ b/src/manpages/standard-conf.xml @@ -0,0 +1,73 @@ +<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<refsection> + <refsection id='confd'> + <title>Configuration Directories and Precedence</title> + + <para>Configuration files are read from directories in + <filename>/etc/</filename>, <filename>/run/</filename>, and + <filename>/usr/lib/</filename>, in order of precedence. + Each configuration file in these configuration directories shall be named in + the style of <filename><replaceable>filename</replaceable>.conf</filename>. + Files in <filename>/etc/</filename> override files with the same name in + <filename>/run/</filename> and <filename>/usr/lib/</filename>. Files in + <filename>/run/</filename> override files with the same name in + <filename>/usr/lib/</filename>.</para> + + <para>Packages should install their configuration files in + <filename>/usr/lib/</filename>. Files in <filename>/etc/</filename> are + reserved for the local administrator, who may use this logic to override the + configuration files installed by vendor packages. All configuration files + are sorted by their filename in lexicographic order, regardless of which of + the directories they reside in. If multiple files specify the same option, + the entry in the file with the lexicographically latest name will take + precedence. It is recommended to prefix all filenames with a two-digit number + and a dash, to simplify the ordering of the files.</para> + + <para>If the administrator wants to disable a configuration file supplied by + the vendor, the recommended way is to place a symlink to + <filename>/dev/null</filename> in the configuration directory in + <filename>/etc/</filename>, with the same filename as the vendor + configuration file. If the vendor configuration file is included in + the initrd image, the image has to be regenerated.</para> + + </refsection> + + <refsection id='main-conf'> + <title>Configuration Directories and Precedence</title> + + <para>The default configuration is defined during compilation, so a + configuration file is only needed when it is necessary to deviate + from those defaults. By default, the configuration file in + <filename>/etc/systemd/</filename> contains commented out entries + showing the defaults as a guide to the administrator. This file + can be edited to create local overrides. + </para> + + <para>When packages need to customize the configuration, they can + install configuration snippets in + <filename>/usr/lib/systemd/*.conf.d/</filename>. Files in + <filename>/etc/</filename> are reserved for the local + administrator, who may use this logic to override the + configuration files installed by vendor packages. The main + configuration file is read before any of the configuration + directories, and has the lowest precedence; entries in a file in + any configuration directory override entries in the single + configuration file. Files in the + <filename>*.conf.d/</filename> configuration subdirectories + are sorted by their filename in lexicographic order, regardless of + which of the subdirectories they reside in. If multiple files + specify the same option, the entry in the file with the + lexicographically latest name takes precedence. It is recommended + to prefix all filenames in those subdirectories with a two-digit + number and a dash, to simplify the ordering of the files.</para> + + <para>To disable a configuration file supplied by the vendor, the + recommended way is to place a symlink to + <filename>/dev/null</filename> in the configuration directory in + <filename>/etc/</filename>, with the same filename as the vendor + configuration file.</para> + </refsection> +</refsection> diff --git a/src/manpages/standard-options.xml b/src/manpages/standard-options.xml new file mode 100644 index 0000000000..f214463392 --- /dev/null +++ b/src/manpages/standard-options.xml @@ -0,0 +1,39 @@ +<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<variablelist> + <varlistentry id='help'> + <term><option>-h</option></term> + <term><option>--help</option></term> + + <listitem id='help-text'> + <para>Print a short help text and exit. + </para></listitem> + </varlistentry> + + <varlistentry id='version'> + <term><option>--version</option></term> + + <listitem id='version-text'> + <para>Print a short version string and exit.</para> + </listitem> + </varlistentry> + + <varlistentry id='no-pager'> + <term><option>--no-pager</option></term> + + <listitem> + <para>Do not pipe output into a pager.</para> + </listitem> + </varlistentry> + + <varlistentry id='no-legend'> + <term><option>--no-legend</option></term> + + <listitem> + <para>Do not print the legend, i.e. column headers and the + footer with hints.</para> + </listitem> + </varlistentry> +</variablelist> diff --git a/src/manpages/sysctl.d.xml b/src/manpages/sysctl.d.xml new file mode 100644 index 0000000000..ccf6c8e39f --- /dev/null +++ b/src/manpages/sysctl.d.xml @@ -0,0 +1,184 @@ +<?xml version="1.0"?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="sysctl.d" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sysctl.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sysctl.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>sysctl.d</refname> + <refpurpose>Configure kernel parameters at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/sysctl.d/*.conf</filename></para> + <para><filename>/run/sysctl.d/*.conf</filename></para> + <para><filename>/usr/lib/sysctl.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>At boot, + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories to configure + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files contain a list of variable + assignments, separated by newlines. Empty lines and lines whose + first non-whitespace character is <literal>#</literal> or + <literal>;</literal> are ignored.</para> + + <para>Note that either <literal>/</literal> or + <literal>.</literal> may be used as separators within sysctl + variable names. If the first separator is a slash, remaining + slashes and dots are left intact. If the first separator is a dot, + dots and slashes are interchanged. + <literal>kernel.domainname=foo</literal> and + <literal>kernel/domainname=foo</literal> are equivalent and will + cause <literal>foo</literal> to be written to + <filename>/proc/sys/kernel/domainname</filename>. Either + <literal>net.ipv4.conf.enp3s0/200.forwarding</literal> or + <literal>net/ipv4/conf/enp3s0.200/forwarding</literal> may be used + to refer to + <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>. + </para> + + <para>The settings configured with <filename>sysctl.d</filename> + files will be applied early on boot. The network + interface-specific options will also be applied individually for + each network interface as it shows up in the system. (More + specifically, <filename>net.ipv4.conf.*</filename>, + <filename>net.ipv6.conf.*</filename>, + <filename>net.ipv4.neigh.*</filename> and + <filename>net.ipv6.neigh.*</filename>).</para> + + <para>Many sysctl parameters only become available when certain + kernel modules are loaded. Modules are usually loaded on demand, + e.g. when certain hardware is plugged in or network brought up. + This means that + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + which runs during early boot will not configure such parameters if + they become available after it has run. To set such parameters, it + is recommended to add an + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + rule to set those parameters when they become available. + Alternatively, a slightly simpler and less efficient option is to + add the module to + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + causing it to be loaded statically before sysctl settings are + applied (see example below).</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Examples</title> + <example> + <title>Set kernel YP domain name</title> + <para><filename>/etc/sysctl.d/domain-name.conf</filename>: + </para> + + <programlisting>kernel.domainname=example.com</programlisting> + </example> + + <example> + <title>Apply settings available only when a certain module is loaded (method one)</title> + <para><filename>/etc/udev/rules.d/99-bridge.rules</filename>: + </para> + + <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \ + RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" +</programlisting> + + <para><filename>/etc/sysctl.d/bridge.conf</filename>: + </para> + + <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 +net.bridge.bridge-nf-call-iptables = 0 +net.bridge.bridge-nf-call-arptables = 0 +</programlisting> + + <para>This method applies settings when the module is + loaded. Please note that, unless the <filename>br_netfilter</filename> + module is loaded, bridged packets will not be filtered by + Netfilter (starting with kernel 3.18), so simply not loading the + module is sufficient to avoid filtering.</para> + </example> + + <example> + <title>Apply settings available only when a certain module is loaded (method two)</title> + <para><filename>/etc/modules-load.d/bridge.conf</filename>: + </para> + + <programlisting>br_netfilter</programlisting> + + <para><filename>/etc/sysctl.d/bridge.conf</filename>: + </para> + + <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 +net.bridge.bridge-nf-call-iptables = 0 +net.bridge.bridge-nf-call-arptables = 0 +</programlisting> + + <para>This method forces the module to be always loaded. Please + note that, unless the <filename>br_netfilter</filename> module is + loaded, bridged packets will not be filtered with Netfilter + (starting with kernel 3.18), so simply not loading the module is + sufficient to avoid filtering.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-ask-password-console.service.xml b/src/manpages/systemd-ask-password-console.service.xml new file mode 100644 index 0000000000..479e5f2e5b --- /dev/null +++ b/src/manpages/systemd-ask-password-console.service.xml @@ -0,0 +1,93 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-ask-password-console.service"> + + <refentryinfo> + <title>systemd-ask-password-console.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-ask-password-console.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-ask-password-console.service</refname> + <refname>systemd-ask-password-console.path</refname> + <refname>systemd-ask-password-wall.service</refname> + <refname>systemd-ask-password-wall.path</refname> + <refpurpose>Query the user for system passwords on the + console and via wall</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-ask-password-console.service</filename></para> + <para><filename>systemd-ask-password-console.path</filename></para> + <para><filename>systemd-ask-password-wall.service</filename></para> + <para><filename>systemd-ask-password-wall.path</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-ask-password-console.service</filename> is + a system service that queries the user for system passwords (such + as hard disk encryption keys and SSL certificate passphrases) on + the console. It is intended to be used during boot to ensure + proper handling of passwords necessary for boot. + <filename>systemd-ask-password-wall.service</filename> is a system + service that informs all logged in users for system passwords via + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + It is intended to be used after boot to ensure that users are + properly notified.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> + developer documentation</ulink> for more information about the + system password logic.</para> + + <para>Note that these services invoke + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with either the <command>--watch --console</command> or + <command>--watch --wall</command> command line parameters.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-cryptsetup-generator.xml b/src/manpages/systemd-cryptsetup-generator.xml new file mode 100644 index 0000000000..f036ab9744 --- /dev/null +++ b/src/manpages/systemd-cryptsetup-generator.xml @@ -0,0 +1,193 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'> + + <refentryinfo> + <title>systemd-cryptsetup-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cryptsetup-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cryptsetup-generator</refname> + <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-cryptsetup-generator</filename> is a + generator that translates <filename>/etc/crypttab</filename> into + native systemd units early at boot and when configuration of the + system manager is reloaded. This will create + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + units as necessary.</para> + + <para><filename>systemd-cryptsetup-generator</filename> implements + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-cryptsetup-generator</filename> + understands the following kernel command line parameters:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>yes</literal>. If <literal>no</literal>, disables the + generator entirely. <varname>rd.luks=</varname> is honored + only by initial RAM disk (initrd) while + <varname>luks=</varname> is honored by both the main system + and the initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>yes</literal>. If <literal>no</literal>, causes the + generator to ignore any devices configured in + <filename>/etc/crypttab</filename> + (<varname>luks.uuid=</varname> will still work however). + <varname>rd.luks.crypttab=</varname> is honored only by + initial RAM disk (initrd) while + <varname>luks.crypttab=</varname> is honored by both the main + system and the initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + + <listitem><para>Takes a LUKS superblock UUID as argument. This + will activate the specified device as part of the boot process + as if it was listed in <filename>/etc/crypttab</filename>. + This option may be specified more than once in order to set up + multiple devices. <varname>rd.luks.uuid=</varname> is honored + only by initial RAM disk (initrd) while + <varname>luks.uuid=</varname> is honored by both the main + system and the initrd.</para> + <para>If /etc/crypttab contains entries with the same UUID, + then the name, keyfile and options specified there will be + used. Otherwise, the device will have the name + <literal>luks-UUID</literal>.</para> + <para>If /etc/crypttab exists, only those UUIDs + specified on the kernel command line + will be activated in the initrd or the real root.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.name=</varname></term> + <term><varname>rd.luks.name=</varname></term> + + <listitem><para>Takes a LUKS super block UUID followed by an + <literal>=</literal> and a name. This implies + <varname>rd.luks.uuid=</varname> or + <varname>luks.uuid=</varname> and will additionally make the + LUKS device given by the UUID appear under the provided + name.</para> + + <para><varname>rd.luks.name=</varname> is honored only by + initial RAM disk (initrd) while <varname>luks.name=</varname> + is honored by both the main system and the initrd.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.options=</varname></term> + <term><varname>rd.luks.options=</varname></term> + + <listitem><para>Takes a LUKS super block UUID followed by an + <literal>=</literal> and a string of options separated by + commas as argument. This will override the options for the + given UUID.</para> + <para>If only a list of options, without an UUID, is + specified, they apply to any UUIDs not specified elsewhere, + and without an entry in + <filename>/etc/crypttab</filename>.</para><para> + <varname>rd.luks.options=</varname> is honored only by initial + RAM disk (initrd) while <varname>luks.options=</varname> is + honored by both the main system and the initrd.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.key=</varname></term> + <term><varname>rd.luks.key=</varname></term> + + <listitem><para>Takes a password file name as argument or a + LUKS super block UUID followed by a <literal>=</literal> and a + password file name.</para> + + <para>For those entries specified with + <varname>rd.luks.uuid=</varname> or + <varname>luks.uuid=</varname>, the password file will be set + to the one specified by <varname>rd.luks.key=</varname> or + <varname>luks.key=</varname> of the corresponding UUID, or the + password file that was specified without a UUID.</para> + <para><varname>rd.luks.key=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks.key=</varname> is + honored by both the main system and + the initrd.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-halt.service.xml b/src/manpages/systemd-halt.service.xml new file mode 100644 index 0000000000..c94e2a1820 --- /dev/null +++ b/src/manpages/systemd-halt.service.xml @@ -0,0 +1,118 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-halt.service"> + + <refentryinfo> + <title>systemd-halt.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-halt.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-halt.service</refname> + <refname>systemd-poweroff.service</refname> + <refname>systemd-reboot.service</refname> + <refname>systemd-kexec.service</refname> + <refname>systemd-shutdown</refname> + <refpurpose>System shutdown logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-halt.service</filename></para> + <para><filename>systemd-poweroff.service</filename></para> + <para><filename>systemd-reboot.service</filename></para> + <para><filename>systemd-kexec.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-halt.service</filename> is a system + service that is pulled in by <filename>halt.target</filename> and + is responsible for the actual system halt. Similarly, + <filename>systemd-poweroff.service</filename> is pulled in by + <filename>poweroff.target</filename>, + <filename>systemd-reboot.service</filename> by + <filename>reboot.target</filename> and + <filename>systemd-kexec.service</filename> by + <filename>kexec.target</filename> to execute the respective + actions.</para> + + <para>When these services are run, they ensure that PID 1 is + replaced by the + <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which + is then responsible for the actual shutdown. Before shutting down, + this binary will try to unmount all remaining file systems, + disable all remaining swap devices, detach all remaining storage + devices and kill all remaining processes.</para> + + <para>It is necessary to have this code in a separate binary + because otherwise rebooting after an upgrade might be broken — the + running PID 1 could still depend on libraries which are not + available any more, thus keeping the file system busy, which then + cannot be re-mounted read-only.</para> + + <para>Immediately before executing the actual system + halt/poweroff/reboot/kexec <filename>systemd-shutdown</filename> + will run all executables in + <filename>/usr/lib/systemd/system-shutdown/</filename> and pass + one arguments to them: either <literal>halt</literal>, + <literal>poweroff</literal>, <literal>reboot</literal> or + <literal>kexec</literal>, depending on the chosen action. All + executables in this directory are executed in parallel, and + execution of the action is not continued before all executables + finished.</para> + + <para>Note that <filename>systemd-halt.service</filename> (and the + related units) should never be executed directly. Instead, trigger + system shutdown with a command such as <literal>systemctl + halt</literal> or suchlike.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-machine-id-commit.service.xml b/src/manpages/systemd-machine-id-commit.service.xml new file mode 100644 index 0000000000..39da1922cc --- /dev/null +++ b/src/manpages/systemd-machine-id-commit.service.xml @@ -0,0 +1,95 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2014 Didier Roche + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-machine-id-commit.service"> + + <refentryinfo> + <title>systemd-machine-id-commit.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-machine-id-commit.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machine-id-commit.service</refname> + <refpurpose>Commit a transient machine ID to disk</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-machine-id-commit.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-machine-id-commit.service</filename> is an + early boot service responsible for committing transient + <filename>/etc/machine-id</filename> files to a writable disk file + system. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about machine IDs.</para> + + <para>This service is started after + <filename>local-fs.target</filename> in case + <filename>/etc/machine-id</filename> is a mount point of its own + (usually from a memory file system such as + <literal>tmpfs</literal>) and /etc is writable. The service will + invoke <command>systemd-machine-id-setup --commit</command>, which + writes the current transient machine ID to disk and unmount the + <filename>/etc/machine-id</filename> file in a race-free manner to + ensure that file is always valid and accessible for other + processes. See + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + + <para>The main use case of this service are systems where + <filename>/etc/machine-id</filename> is read-only and initially + not initialized. In this case, the system manager will generate a + transient machine ID file on a memory file system, and mount it + over <filename>/etc/machine-id</filename>, during the early boot + phase. This service is then invoked in a later boot phase, as soon + as <filename>/etc</filename> has been remounted writable and the + ID may thus be committed to disk to make it permanent.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-suspend.service.xml b/src/manpages/systemd-suspend.service.xml new file mode 100644 index 0000000000..a8beb86f4d --- /dev/null +++ b/src/manpages/systemd-suspend.service.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + Copyright 2013 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-suspend.service" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-suspend.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-suspend.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-suspend.service</refname> + <refname>systemd-hibernate.service</refname> + <refname>systemd-hybrid-sleep.service</refname> + <refname>systemd-sleep</refname> + <refpurpose>System sleep state logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-suspend.service</filename></para> + <para><filename>systemd-hibernate.service</filename></para> + <para><filename>systemd-hybrid-sleep.service</filename></para> + <para><filename>/usr/lib/systemd/system-sleep</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-suspend.service</filename> is a system + service that is pulled in by <filename>suspend.target</filename> + and is responsible for the actual system suspend. Similarly, + <filename>systemd-hibernate.service</filename> is pulled in by + <filename>hibernate.target</filename> to execute the actual + hibernation. Finally, + <filename>systemd-hybrid-sleep.service</filename> is pulled in by + <filename>hybrid-sleep.target</filename> to execute hybrid + hibernation with system suspend.</para> + + <para>Immediately before entering system suspend and/or + hibernation <filename>systemd-suspend.service</filename> (and the + other mentioned units, respectively) will run all executables in + <filename>/usr/lib/systemd/system-sleep/</filename> and pass two + arguments to them. The first argument will be + <literal>pre</literal>, the second either + <literal>suspend</literal>, <literal>hibernate</literal>, or + <literal>hybrid-sleep</literal> depending on the chosen action. + Immediately after leaving system suspend and/or hibernation the + same executables are run, but the first argument is now + <literal>post</literal>. All executables in this directory are + executed in parallel, and execution of the action is not continued + until all executables have finished.</para> + + <para>Note that scripts or binaries dropped in + <filename>/usr/lib/systemd/system-sleep/</filename> are intended + for local use only and should be considered hacks. If applications + want to be notified of system suspend/hibernation and resume, + there are much nicer interfaces available.</para> + + <para>Note that + <filename>systemd-suspend.service</filename>, + <filename>systemd-hibernate.service</filename>, and + <filename>systemd-hybrid-sleep.service</filename> + should never be executed directly. Instead, trigger system sleep + states with a command such as <literal>systemctl suspend</literal> + or similar.</para> + + <para>Internally, this service will echo a string like + <literal>mem</literal> into <filename>/sys/power/state</filename>, + to trigger the actual system suspend. What exactly is written + where can be configured in the <literal>[Sleep]</literal> section + of <filename>/etc/systemd/sleep.conf</filename> or a + <filename>sleep.conf.d</filename> file. See + <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para><command>systemd-sleep</command> understands the + following commands:</para> + + <variablelist> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + + <varlistentry> + <term><option>suspend</option></term> + <term><option>hibernate</option></term> + <term><option>hybrid-sleep</option></term> + + <listitem><para>Suspend, hibernate, or put the system to + hybrid sleep.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/systemd-system.conf.xml b/src/manpages/systemd-system.conf.xml new file mode 100644 index 0000000000..8833e73c72 --- /dev/null +++ b/src/manpages/systemd-system.conf.xml @@ -0,0 +1,394 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-system.conf" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>systemd-system.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-system.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-system.conf</refname> + <refname>system.conf.d</refname> + <refname>systemd-user.conf</refname> + <refname>user.conf.d</refname> + <refpurpose>System and session service manager configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system.conf</filename>, + <filename>/etc/systemd/system.conf.d/*.conf</filename>, + <filename>/run/systemd/system.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/user.conf</filename>, + <filename>/etc/systemd/user.conf.d/*.conf</filename>, + <filename>/run/systemd/user.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. These configuration + files contain a few settings controlling basic manager + operations.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Manager]</literal> section:</para> + + <variablelist class='systemd-directives'> + + <varlistentry> + <term><varname>LogLevel=</varname></term> + <term><varname>LogTarget=</varname></term> + <term><varname>LogColor=</varname></term> + <term><varname>LogLocation=</varname></term> + <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashChangeVT=no</varname></term> + <term><varname>CrashShell=no</varname></term> + <term><varname>CrashReboot=no</varname></term> + <term><varname>ShowStatus=yes</varname></term> + <term><varname>DefaultStandardOutput=journal</varname></term> + <term><varname>DefaultStandardError=inherit</varname></term> + + <listitem><para>Configures various parameters of basic manager + operation. These options may be overridden by the respective + command line arguments. See + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about these command line + arguments.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Configures the initial CPU affinity for the + init process. Takes a list of CPU indices or ranges separated + by either whitespace or commas. CPU ranges are specified by + the lower and upper CPU indices separated by a + dash.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinControllers=cpu,cpuacct net_cls,netprio</varname></term> + + <listitem><para>Configures controllers that shall be mounted + in a single hierarchy. By default, systemd will mount all + controllers which are enabled in the kernel in individual + hierarchies, with the exception of those listed in this + setting. Takes a space-separated list of comma-separated + controller names, in order to allow multiple joined + hierarchies. Defaults to 'cpu,cpuacct'. Pass an empty string + to ensure that systemd mounts all controllers in separate + hierarchies.</para> + + <para>Note that this option is only applied once, at very + early boot. If you use an initial RAM disk (initrd) that uses + systemd, it might hence be necessary to rebuild the initrd if + this option is changed, and make sure the new configuration + file is included in it. Otherwise, the initrd might mount the + controller hierarchies in a different configuration than + intended, and the main system cannot remount them + anymore.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeWatchdogSec=</varname></term> + <term><varname>ShutdownWatchdogSec=</varname></term> + + <listitem><para>Configure the hardware watchdog at runtime and + at reboot. Takes a timeout value in seconds (or in other time + units if suffixed with <literal>ms</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>d</literal>, <literal>w</literal>). If + <varname>RuntimeWatchdogSec=</varname> is set to a non-zero + value, the watchdog hardware + (<filename>/dev/watchdog</filename>) will be programmed to + automatically reboot the system if it is not contacted within + the specified timeout interval. The system manager will ensure + to contact it at least once in half the specified timeout + interval. This feature requires a hardware watchdog device to + be present, as it is commonly the case in embedded and server + systems. Not all hardware watchdogs allow configuration of the + reboot timeout, in which case the closest available timeout is + picked. <varname>ShutdownWatchdogSec=</varname> may be used to + configure the hardware watchdog when the system is asked to + reboot. It works as a safety net to ensure that the reboot + takes place even if a clean reboot attempt times out. By + default <varname>RuntimeWatchdogSec=</varname> defaults to 0 + (off), and <varname>ShutdownWatchdogSec=</varname> to 10min. + These settings have no effect if a hardware watchdog is not + available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which capabilities to include in the + capability bounding set for PID 1 and its children. See + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details. Takes a whitespace-separated list of capability + names as read by + <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Capabilities listed will be included in the bounding set, all + others are removed. If the list of capabilities is prefixed + with ~, all but the listed capabilities will be included, the + effect of the assignment inverted. Note that this option also + affects the respective capabilities in the effective, + permitted and inheritable capability sets. The capability + bounding set may also be individually configured for units + using the <varname>CapabilityBoundingSet=</varname> directive + for units, but note that capabilities dropped for PID 1 cannot + be regained in individual units, they are lost for + good.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallArchitectures=</varname></term> + + <listitem><para>Takes a space-separated list of architecture + identifiers. Selects from which architectures system calls may + be invoked on this system. This may be used as an effective + way to disable invocation of non-native binaries system-wide, + for example to prohibit execution of 32-bit x86 binaries on + 64-bit x86-64 systems. This option operates system-wide, and + acts similar to the + <varname>SystemCallArchitectures=</varname> setting of unit + files, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting defaults to the empty list, in which + case no filtering of system calls based on architecture is + applied. Known architecture identifiers are + <literal>x86</literal>, <literal>x86-64</literal>, + <literal>x32</literal>, <literal>arm</literal> and the special + identifier <literal>native</literal>. The latter implicitly + maps to the native architecture of the system (or more + specifically, the architecture the system manager was compiled + for). Set this setting to <literal>native</literal> to + prohibit execution of any non-native binaries. When a binary + executes a system call of an architecture that is not listed + in this setting, it will be immediately terminated with the + SIGSYS signal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + + <listitem><para>Sets the timer slack in nanoseconds for PID 1, + which is inherited by all executed processes, unless + overridden individually, for example with the + <varname>TimerSlackNSec=</varname> setting in service units + (for details see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The timer slack controls the accuracy of wake-ups triggered by + system timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in contrast to most other time + span definitions this parameter takes an integer value in + nano-seconds if no unit is specified. The usual time units are + understood too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimerAccuracySec=</varname></term> + + <listitem><para>Sets the default accuracy of timer units. This + controls the global default for the + <varname>AccuracySec=</varname> setting of timer units, see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. <varname>AccuracySec=</varname> set in individual + units override the global default for the specific unit. + Defaults to 1min. Note that the accuracy of timer units is + also affected by the configured timer slack for PID 1, see + <varname>TimerSlackNSec=</varname> above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimeoutStartSec=</varname></term> + <term><varname>DefaultTimeoutStopSec=</varname></term> + <term><varname>DefaultRestartSec=</varname></term> + + <listitem><para>Configures the default timeouts for starting + and stopping of units, as well as the default time to sleep + between automatic restarts of units, as configured per-unit in + <varname>TimeoutStartSec=</varname>, + <varname>TimeoutStopSec=</varname> and + <varname>RestartSec=</varname> (for services, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit settings). For non-service units, + <varname>DefaultTimeoutStartSec=</varname> sets the default + <varname>TimeoutSec=</varname> + value. <varname>DefaultTimeoutStartSec=</varname> and + <varname>DefaultTimeoutStopSec=</varname> default to + 90s. <varname>DefaultRestartSec=</varname> defaults to + 100ms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultStartLimitIntervalSec=</varname></term> + <term><varname>DefaultStartLimitBurst=</varname></term> + + <listitem><para>Configure the default unit start rate + limiting, as configured per-service by + <varname>StartLimitIntervalSec=</varname> and + <varname>StartLimitBurst=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-service settings. + <varname>DefaultStartLimitIntervalSec=</varname> defaults to + 10s. <varname>DefaultStartLimitBurst=</varname> defaults to + 5.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultEnvironment=</varname></term> + + <listitem><para>Sets manager environment variables passed to + all executed processes. Takes a space-separated list of + variable assignments. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para> + + <para>Example: + + <programlisting>DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting> + + Sets three variables + <literal>VAR1</literal>, + <literal>VAR2</literal>, + <literal>VAR3</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultCPUAccounting=</varname></term> + <term><varname>DefaultBlockIOAccounting=</varname></term> + <term><varname>DefaultMemoryAccounting=</varname></term> + <term><varname>DefaultTasksAccounting=</varname></term> + + <listitem><para>Configure the default resource accounting + settings, as configured per-unit by + <varname>CPUAccounting=</varname>, + <varname>BlockIOAccounting=</varname>, + <varname>MemoryAccounting=</varname> and + <varname>TasksAccounting=</varname>. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit + settings. <varname>DefaulTasksAccounting=</varname> defaults + to on, the other three settings to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTasksMax=</varname></term> + + <listitem><para>Configure the default value for the per-unit + <varname>TasksMax=</varname> setting. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting applies to all unit types that + support resource control settings, with the exception of slice + units. Defaults to 512.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLimitCPU=</varname></term> + <term><varname>DefaultLimitFSIZE=</varname></term> + <term><varname>DefaultLimitDATA=</varname></term> + <term><varname>DefaultLimitSTACK=</varname></term> + <term><varname>DefaultLimitCORE=</varname></term> + <term><varname>DefaultLimitRSS=</varname></term> + <term><varname>DefaultLimitNOFILE=</varname></term> + <term><varname>DefaultLimitAS=</varname></term> + <term><varname>DefaultLimitNPROC=</varname></term> + <term><varname>DefaultLimitMEMLOCK=</varname></term> + <term><varname>DefaultLimitLOCKS=</varname></term> + <term><varname>DefaultLimitSIGPENDING=</varname></term> + <term><varname>DefaultLimitMSGQUEUE=</varname></term> + <term><varname>DefaultLimitNICE=</varname></term> + <term><varname>DefaultLimitRTPRIO=</varname></term> + <term><varname>DefaultLimitRTTIME=</varname></term> + + <listitem><para>These settings control various default + resource limits for units. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. The resource limit is possible to specify in two formats, + <option>value</option> to set soft and hard limits to the same value, + or <option>soft:hard</option> to set both limits individually (e.g. DefaultLimitAS=4G:16G). + Use the string <varname>infinity</varname> to + configure no limit on a specific resource. The multiplicative + suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E + may be used for resource limits measured in bytes + (e.g. DefaultLimitAS=16G). For the limits referring to time values, + the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Note that if no time unit is specified for + <varname>DefaultLimitCPU=</varname> the default unit of seconds is + implied, while for <varname>DefaultLimitRTTIME=</varname> the default + unit of microseconds is implied. Also, note that the effective + granularity of the limits might influence their + enforcement. For example, time limits specified for + <varname>DefaultLimitCPU=</varname> will be rounded up implicitly to + multiples of 1s. These settings may be overridden in individual units + using the corresponding LimitXXX= directives. Note that these resource + limits are only defaults for units, they are not applied to PID 1 + itself.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/sysusers.d.xml b/src/manpages/sysusers.d.xml new file mode 100644 index 0000000000..18ee3800d6 --- /dev/null +++ b/src/manpages/sysusers.d.xml @@ -0,0 +1,223 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="sysusers.d" conditional='ENABLE_SYSUSERS' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sysusers.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sysusers.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>sysusers.d</refname> + <refpurpose>Declarative allocation of system users and groups</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/sysusers.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-sysusers</command> uses the files from + <filename>sysusers.d</filename> directory to create system users + and groups at package installation or boot time. This tool may be + used to allocate system users and groups only, it is not useful + for creating non-system users and groups, as it accesses + <filename>/etc/passwd</filename> and + <filename>/etc/group</filename> directly, bypassing any more + complex user databases, for example any database involving NIS or + LDAP.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each configuration file shall be named in the style of + <filename><replaceable>package</replaceable>.conf</filename> or + <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. + The second variant should be used when it is desirable to make it + easy to override just this part of configuration.</para> + + <para>The file format is one line per user or group containing + name, ID, GECOS field description and home directory:</para> + + <programlisting># Type Name ID GECOS +u httpd 440 "HTTP User" +u authd /usr/bin/authd "Authorization user" +g input - - +m authd input +u root 0 "Superuser" /root</programlisting> + + <refsect2> + <title>Type</title> + + <para>The type consists of a single letter. The following line + types are understood:</para> + + <variablelist> + <varlistentry> + <term><varname>u</varname></term> + <listitem><para>Create a system user and group of the + specified name should they not exist yet. The user's primary + group will be set to the group bearing the same name. The + user's shell will be set to + <filename>/sbin/nologin</filename>, the home directory to + the specified home directory, or <filename>/</filename> if + none is given. The account will be created disabled, so that + logins are not allowed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>g</varname></term> + <listitem><para>Create a system group of the specified name + should it not exist yet. Note that <varname>u</varname> + implicitly create a matching group. The group will be + created with no password set.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>m</varname></term> + <listitem><para>Add a user to a group. If the user or group + do not exist yet, they will be implicitly + created.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>r</varname></term> + <listitem><para>Add a range of numeric UIDs/GIDs to the pool + to allocate new UIDs and GIDs from. If no line of this type + is specified, the range of UIDs/GIDs is set to some + compiled-in default. Note that both UIDs and GIDs are + allocated from the same pool, in order to ensure that users + and groups of the same name are likely to carry the same + numeric UID and GID.</para></listitem> + </varlistentry> + + </variablelist> + </refsect2> + + <refsect2> + <title>Name</title> + + <para>The name field specifies the user or group name. It should + be shorter than 31 characters and avoid any non-ASCII + characters, and not begin with a numeric character. It is + strongly recommended to pick user and group names that are + unlikely to clash with normal users created by the + administrator. A good scheme to guarantee this is by prefixing + all system and group names with the underscore, and avoiding too + generic names.</para> + + <para>For <varname>m</varname> lines, this field should contain + the user name to add to a group.</para> + + <para>For lines of type <varname>r</varname>, this field should + be set to <literal>-</literal>.</para> + </refsect2> + + <refsect2> + <title>ID</title> + + <para>For <varname>u</varname> and <varname>g</varname>, the + numeric 32-bit UID or GID of the user/group. Do not use IDs 65535 + or 4294967295, as they have special placeholder meanings. + Specify <literal>-</literal> for automatic UID/GID allocation + for the user or group. Alternatively, specify an absolute path + in the file system. In this case, the UID/GID is read from the + path's owner/group. This is useful to create users whose UID/GID + match the owners of pre-existing files (such as SUID or SGID + binaries).</para> + + <para>For <varname>m</varname> lines, this field should contain + the group name to add to a user to.</para> + + <para>For lines of type <varname>r</varname>, this field should + be set to a UID/GID range in the format + <literal>FROM-TO</literal>, where both values are formatted as + decimal ASCII numbers. Alternatively, a single UID/GID may be + specified formatted as decimal ASCII numbers.</para> + </refsect2> + + <refsect2> + <title>GECOS</title> + + <para>A short, descriptive string for users to be created, + enclosed in quotation marks. Note that this field may not + contain colons.</para> + + <para>Only applies to lines of type <varname>u</varname> and + should otherwise be left unset, or be set to + <literal>-</literal>.</para> + </refsect2> + + <refsect2> + <title>Home Directory</title> + + <para>The home directory for a new system user. If omitted, + defaults to the root directory. It is recommended to not + unnecessarily specify home directories for system users, unless + software strictly requires one to be set.</para> + + <para>Only applies to lines of type <varname>u</varname> and + should otherwise be left unset, or be set to + <literal>-</literal>.</para> + </refsect2> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Idempotence</title> + + <para>Note that <command>systemd-sysusers</command> will do + nothing if the specified users or groups already exist, so + normally, there is no reason to override + <filename>sysusers.d</filename> vendor configuration, except to + block certain users or groups from being created.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/telinit.xml b/src/manpages/telinit.xml new file mode 100644 index 0000000000..02d31fbd46 --- /dev/null +++ b/src/manpages/telinit.xml @@ -0,0 +1,179 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="telinit" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>telinit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>telinit</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>telinit</refname> + <refpurpose>Change SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>telinit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>telinit</command> may be used to change the SysV + system runlevel. Since the concept of SysV runlevels is obsolete + the runlevel requests will be transparently translated into + systemd unit activation requests.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall message before + reboot/halt/power-off.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>0</command></term> + + <listitem><para>Power-off the machine. This is translated into + an activation request for <filename>poweroff.target</filename> + and is equivalent to <command>systemctl + poweroff</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>6</command></term> + + <listitem><para>Reboot the machine. This is translated into an + activation request for <filename>reboot.target</filename> and + is equivalent to <command>systemctl + reboot</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>2</command></term> + <term><command>3</command></term> + <term><command>4</command></term> + <term><command>5</command></term> + + <listitem><para>Change the SysV runlevel. This is translated + into an activation request for + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, ... and is equivalent + to <command>systemctl isolate runlevel2.target</command>, + <command>systemctl isolate runlevel3.target</command>, + ...</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>1</command></term> + <term><command>s</command></term> + <term><command>S</command></term> + + <listitem><para>Change into system rescue mode. This is + translated into an activation request for + <filename>rescue.target</filename> and is equivalent to + <command>systemctl rescue</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>q</command></term> + <term><command>Q</command></term> + + <listitem><para>Reload daemon configuration. This is + equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>u</command></term> + <term><command>U</command></term> + + <listitem><para>Serialize state, reexecute daemon and + deserialize state again. This is equivalent to + <command>systemctl daemon-reexec</command>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for compatibility only. + It should not be used anymore, as the concept of runlevels is + obsolete.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/timesyncd.conf.xml b/src/manpages/timesyncd.conf.xml new file mode 100644 index 0000000000..8c86fd0074 --- /dev/null +++ b/src/manpages/timesyncd.conf.xml @@ -0,0 +1,112 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="timesyncd.conf" conditional='ENABLE_TIMESYNCD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>timesyncd.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>timesyncd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>timesyncd.conf</refname> + <refname>timesyncd.conf.d</refname> + <refpurpose>Network Time Synchronization configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/timesyncd.conf</filename></para> + <para><filename>/etc/systemd/timesyncd.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/timesyncd.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/timesyncd.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control NTP network time + synchronization.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>The following settings are configured in the <literal>[Time]</literal> section:</para> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>NTP=</varname></term> + <listitem><para>A space-separated list of NTP server host + names or IP addresses. During runtime this list is combined + with any per-interface NTP servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + systemd-timesyncd will contact all configured system or + per-interface servers in turn until one is found that + responds. This setting defaults to an empty + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FallbackNTP=</varname></term> + <listitem><para>A space-separated list of NTP server host + names or IP addresses to be used as the fallback NTP servers. + Any per-interface NTP servers obtained from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + take precedence over this setting, as do any servers set via + <varname>NTP=</varname> above. This setting is hence only used + if no other NTP server information is known. If this option is + not given, a compiled-in list of NTP servers is used + instead.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/tmpfiles.d.xml b/src/manpages/tmpfiles.d.xml new file mode 100644 index 0000000000..957475d2bd --- /dev/null +++ b/src/manpages/tmpfiles.d.xml @@ -0,0 +1,703 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2010 Brandon Philips + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="tmpfiles.d"> + + <refentryinfo> + <title>tmpfiles.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Brandon</firstname> + <surname>Philips</surname> + <email>brandon@ifup.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>tmpfiles.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>tmpfiles.d</refname> + <refpurpose>Configuration for creation, deletion and cleaning of + volatile and temporary files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/tmpfiles.d/*.conf</filename></para> + <para><filename>/run/tmpfiles.d/*.conf</filename></para> + <para><filename>/usr/lib/tmpfiles.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-tmpfiles</command> uses the configuration + files from the above directories to describe the creation, + cleaning and removal of volatile and temporary files and + directories which usually reside in directories such as + <filename>/run</filename> or <filename>/tmp</filename>.</para> + + <para>Volatile and temporary files and directories are those + located in <filename>/run</filename> (and its alias + <filename>/var/run</filename>), <filename>/tmp</filename>, + <filename>/var/tmp</filename>, the API file systems such as + <filename>/sys</filename> or <filename>/proc</filename>, as well + as some other directories below <filename>/var</filename>.</para> + + <para>System daemons frequently require private runtime + directories below <filename>/run</filename> to place communication + sockets and similar in. For these, consider declaring them in + their unit files using <varname>RuntimeDirectory=</varname> (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details), if this is feasible.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each configuration file shall be named in the style of + <filename><replaceable>package</replaceable>.conf</filename> or + <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. + The second variant should be used when it is desirable to make it + easy to override just this part of configuration.</para> + + <para>Files in <filename>/etc/tmpfiles.d</filename> override files + with the same name in <filename>/usr/lib/tmpfiles.d</filename> and + <filename>/run/tmpfiles.d</filename>. Files in + <filename>/run/tmpfiles.d</filename> override files with the same + name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should + install their configuration files in + <filename>/usr/lib/tmpfiles.d</filename>. Files in + <filename>/etc/tmpfiles.d</filename> are reserved for the local + administrator, who may use this logic to override the + configuration files installed by vendor packages. All + configuration files are sorted by their filename in lexicographic + order, regardless of which of the directories they reside in. If + multiple files specify the same path, the entry in the file with + the lexicographically earliest name will be applied. All other + conflicting entries will be logged as errors. When two lines are + prefix and suffix of each other, then the prefix is always + processed first, the suffix later. Lines that take globs are + applied after those accepting no globs. If multiple operations + shall be applied on the same file, (such as ACL, xattr, file + attribute adjustments), these are always done in the same fixed + order. Otherwise, the files/directories are processed in the order + they are listed.</para> + + <para>If the administrator wants to disable a configuration file + supplied by the vendor, the recommended way is to place a symlink + to <filename>/dev/null</filename> in + <filename>/etc/tmpfiles.d/</filename> bearing the same filename. + </para> + + <para>The configuration format is one line per path containing + type, path, mode, ownership, age, and argument fields:</para> + + <programlisting>#Type Path Mode UID GID Age Argument + d /run/user 0755 root root 10d - + L /tmp/foobar - - - - /dev/null</programlisting> + + <para>Fields may be enclosed within quotes and contain C-style escapes.</para> + + <refsect2> + <title>Type</title> + + <para>The type consists of a single letter and optionally an + exclamation mark.</para> + + <para>The following line types are understood:</para> + + <variablelist> + <varlistentry> + <term><varname>f</varname></term> + <listitem><para>Create a file if it does not exist yet. If + the argument parameter is given, it will be written to the + file. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>F</varname></term> + <listitem><para>Create or truncate a file. If the argument + parameter is given, it will be written to the file. Does not follow symlinks.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>w</varname></term> + <listitem><para>Write the argument parameter to a file, if + the file exists. Lines of this type accept shell-style + globs in place of normal path names. The argument parameter + will be written without a trailing newline. C-style + backslash escapes are interpreted. Follows + symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>d</varname></term> + <listitem><para>Create a directory. The mode and ownership will be adjusted if + specified and the directory already exists. Contents of this directory are subject + to time based cleanup if the time argument is specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>D</varname></term> + <listitem><para>Similar to <varname>d</varname>, but in addition the contents + of the directory will be removed when <option>--remove</option> is used. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>e</varname></term> + <listitem><para>Similar to <varname>d</varname>, but the directory will not be + created if it does not exist. Lines of this type accept shell-style globs in + place of normal path names.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>v</varname></term> + <listitem><para>Create a subvolume if the path does not + exist yet, the file system supports subvolumes (btrfs), and + the system itself is installed into a subvolume + (specifically: the root directory <filename>/</filename> is + itself a subvolume). Otherwise, create a normal directory, in + the same way as <varname>d</varname>. A subvolume created + with this line type is not assigned to any higher-level + quota group. For that, use <varname>q</varname> or + <varname>Q</varname>, which allow creating simple quota + group hierarchies, see below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>q</varname></term> + <listitem><para>Similar to <varname>v</varname>. However, + makes sure that the subvolume will be assigned to the same + higher-level quota groups as the subvolume it has been + created in. This ensures that higher-level limits and + accounting applied to the parent subvolume also include the + specified subvolume. On non-btrfs file systems, this line + type is identical to <varname>d</varname>. If the subvolume + already exists and is already assigned to one or more higher + level quota groups, no change to the quota hierarchy is + made. Also see <varname>Q</varname> below. See <citerefentry + project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the btrfs quota group + concept.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Q</varname></term> + <listitem><para>Similar to <varname>q</varname>. However, + instead of copying the higher-level quota group assignments + from the parent as-is, the lowest quota group of the parent + subvolume is determined that is not the leaf quota + group. Then, an "intermediary" quota group is inserted that + is one level below this level, and shares the same ID part + as the specified subvolume. If no higher-level quota group + exists for the parent subvolume, a new quota group at level + 255 sharing the same ID as the specified subvolume is + inserted instead. This new intermediary quota group is then + assigned to the parent subvolume's higher-level quota + groups, and the specified subvolume's leaf quota group is + assigned to it.</para> + + <para>Effectively, this has a similar effect as + <varname>q</varname>, however introduces a new higher-level + quota group for the specified subvolume that may be used to + enforce limits and accounting to the specified subvolume and + children subvolume created within it. Thus, by creating + subvolumes only via <varname>q</varname> and + <varname>Q</varname>, a concept of "subtree quotas" is + implemented. Each subvolume for which <varname>Q</varname> + is set will get a "subtree" quota group created, and all + child subvolumes created within it will be assigned to + it. Each subvolume for which <varname>q</varname> is set + will not get such a "subtree" quota group, but it is ensured + that they are added to the same "subtree" quota group as their + immediate parents.</para> + + <para>It is recommended to use + <varname>Q</varname> for subvolumes that typically contain + further subvolumes, and where it is desirable to have + accounting and quota limits on all child subvolumes + together. Examples for <varname>Q</varname> are typically + <filename>/home</filename> or + <filename>/var/lib/machines</filename>. In contrast, + <varname>q</varname> should be used for subvolumes that + either usually do not include further subvolumes or where no + accounting and quota limits are needed that apply to all + child subvolumes together. Examples for <varname>q</varname> + are typically <filename>/var</filename> or + <filename>/var/tmp</filename>. As with <varname>Q</varname>, + <varname>q</varname> has no effect on the quota group + hierarchy if the subvolume exists and already has at least + one higher-level quota group assigned.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>p</varname></term> + <term><varname>p+</varname></term> + <listitem><para>Create a named pipe (FIFO) if it does not + exist yet. If suffixed with <varname>+</varname> and a file + already exists where the pipe is to be created, it will be + removed and be replaced by the pipe.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>L</varname></term> + <term><varname>L+</varname></term> + <listitem><para>Create a symlink if it does not exist + yet. If suffixed with <varname>+</varname> and a file + already exists where the symlink is to be created, it will + be removed and be replaced by the symlink. If the argument + is omitted, symlinks to files with the same name residing in + the directory <filename>/usr/share/factory/</filename> are + created. Note that permissions and ownership on symlinks + are ignored.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>c</varname></term> + <term><varname>c+</varname></term> + <listitem><para>Create a character device node if it does + not exist yet. If suffixed with <varname>+</varname> and a + file already exists where the device node is to be created, + it will be removed and be replaced by the device node. It is + recommended to suffix this entry with an exclamation mark to + only create static device nodes at boot, as udev will not + manage static device nodes that are created at runtime. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>b</varname></term> + <term><varname>b+</varname></term> + <listitem><para>Create a block device node if it does not + exist yet. If suffixed with <varname>+</varname> and a file + already exists where the device node is to be created, it + will be removed and be replaced by the device node. It is + recommended to suffix this entry with an exclamation mark to + only create static device nodes at boot, as udev will not + manage static device nodes that are created at runtime. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>C</varname></term> + <listitem><para>Recursively copy a file or directory, if the + destination files or directories do not exist yet. Note that + this command will not descend into subdirectories if the + destination directory already exists. Instead, the entire + copy operation is skipped. If the argument is omitted, files + from the source directory + <filename>/usr/share/factory/</filename> with the same name + are copied. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>x</varname></term> + <listitem><para>Ignore a path during cleaning. Use this type + to exclude paths from clean-up as controlled with the Age + parameter. Note that lines of this type do not influence the + effect of <varname>r</varname> or <varname>R</varname> + lines. Lines of this type accept shell-style globs in place + of normal path names. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>X</varname></term> + <listitem><para>Ignore a path during cleaning. Use this type + to exclude paths from clean-up as controlled with the Age + parameter. Unlike <varname>x</varname>, this parameter will + not exclude the content if path is a directory, but only + directory itself. Note that lines of this type do not + influence the effect of <varname>r</varname> or + <varname>R</varname> lines. Lines of this type accept + shell-style globs in place of normal path names. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>r</varname></term> + <listitem><para>Remove a file or directory if it exists. + This may not be used to remove non-empty directories, use + <varname>R</varname> for that. Lines of this type accept + shell-style globs in place of normal path + names. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>R</varname></term> + <listitem><para>Recursively remove a path and all its + subdirectories (if it is a directory). Lines of this type + accept shell-style globs in place of normal path + names. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>z</varname></term> + <listitem><para>Adjust the access mode, group and user, and + restore the SELinux security context of a file or directory, + if it exists. Lines of this type accept shell-style globs in + place of normal path names. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Z</varname></term> + <listitem><para>Recursively set the access mode, group and + user, and restore the SELinux security context of a file or + directory if it exists, as well as of its subdirectories and + the files contained therein (if applicable). Lines of this + type accept shell-style globs in place of normal path + names. Does not follow symlinks. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>t</varname></term> + <listitem><para>Set extended attributes. Lines of this type + accept shell-style globs in place of normal path names. + This can be useful for setting SMACK labels. Does not follow + symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>T</varname></term> + <listitem><para>Recursively set extended attributes. Lines + of this type accept shell-style globs in place of normal + path names. This can be useful for setting SMACK + labels. Does not follow symlinks. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>h</varname></term> + <listitem><para>Set file/directory attributes. Lines of this type + accept shell-style globs in place of normal path names.</para> + + <para>The format of the argument field is + <varname>[+-=][aAcCdDeijsStTu] </varname>. The prefix + <varname>+</varname> (the default one) causes the + attribute(s) to be added; <varname>-</varname> causes the + attribute(s) to be removed; <varname>=</varname> causes the + attributes to be set exactly as the following letters. The + letters <literal>aAcCdDeijsStTu</literal> select the new + attributes for the files, see + <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> for further information. + </para> + <para>Passing only <varname>=</varname> as argument resets + all the file attributes listed above. It has to be pointed + out that the <varname>=</varname> prefix limits itself to + the attributes corresponding to the letters listed here. All + other attributes will be left untouched. Does not follow + symlinks.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>H</varname></term> + <listitem><para>Recursively set file/directory attributes. Lines + of this type accept shell-style globs in place of normal + path names. Does not follow symlinks. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>a</varname></term> + <term><varname>a+</varname></term> + <listitem><para>Set POSIX ACLs (access control lists). If + suffixed with <varname>+</varname>, the specified entries will + be added to the existing set. + <command>systemd-tmpfiles</command> will automatically add + the required base entries for user and group based on the + access mode of the file, unless base entries already exist + or are explicitly specified. The mask will be added if not + specified explicitly or already present. Lines of this type + accept shell-style globs in place of normal path names. This + can be useful for allowing additional access to certain + files. Does not follow symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>A</varname></term> + <term><varname>A+</varname></term> + <listitem><para>Same as <varname>a</varname> and + <varname>a+</varname>, but recursive. Does not follow + symlinks.</para></listitem> + </varlistentry> + </variablelist> + + <para>If the exclamation mark is used, this line is only safe of + execute during boot, and can break a running system. Lines + without the exclamation mark are presumed to be safe to execute + at any time, e.g. on package upgrades. + <command>systemd-tmpfiles</command> will execute line with an + exclamation mark only if option <option>--boot</option> is + given.</para> + + <para>For example: + <programlisting># Make sure these are created by default so that nobody else can + d /tmp/.X11-unix 1777 root root 10d + + # Unlink the X11 lock files + r! /tmp/.X[0-9]*-lock</programlisting> + The second line in contrast to the first one would break a + running system, and will only be executed with + <option>--boot</option>.</para> + </refsect2> + + <refsect2> + <title>Path</title> + + <para>The file system path specification supports simple + specifier expansion. The following expansions are + understood:</para> + + <table> + <title>Specifiers available</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="spec" /> + <colspec colname="mean" /> + <colspec colname="detail" /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Meaning</entry> + <entry>Details</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%m</literal></entry> + <entry>Machine ID</entry> + <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Boot ID</entry> + <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%H</literal></entry> + <entry>Host name</entry> + <entry>The hostname of the running system.</entry> + </row> + <row> + <entry><literal>%v</literal></entry> + <entry>Kernel release</entry> + <entry>Identical to <command>uname -r</command> output.</entry> + </row> + <row> + <entry><literal>%%</literal></entry> + <entry>Escaped %</entry> + <entry>Single percent sign.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect2> + + <refsect2> + <title>Mode</title> + + <para>The file access mode to use when creating this file or + directory. If omitted or when set to <literal>-</literal>, the + default is used: 0755 for directories, 0644 for all other file + objects. For <varname>z</varname>, <varname>Z</varname> lines, + if omitted or when set to <literal>-</literal>, the file access + mode will not be modified. This parameter is ignored for + <varname>x</varname>, <varname>r</varname>, + <varname>R</varname>, <varname>L</varname>, <varname>t</varname>, + and <varname>a</varname> lines.</para> + + <para>Optionally, if prefixed with <literal>~</literal>, the + access mode is masked based on the already set access bits for + existing file or directories: if the existing file has all + executable bits unset, all executable bits are removed from the + new access mode, too. Similarly, if all read bits are removed + from the old access mode, they will be removed from the new + access mode too, and if all write bits are removed, they will be + removed from the new access mode too. In addition, the + sticky/SUID/SGID bit is removed unless applied to a + directory. This functionality is particularly useful in + conjunction with <varname>Z</varname>.</para> + </refsect2> + + <refsect2> + <title>UID, GID</title> + + <para>The user and group to use for this file or directory. This + may either be a numeric user/group ID or a user or group + name. If omitted or when set to <literal>-</literal>, the + default 0 (root) is used. For <varname>z</varname> and + <varname>Z</varname> lines, when omitted or when set to + <literal>-</literal>, the file ownership will not be + modified. These parameters are ignored for <varname>x</varname>, + <varname>r</varname>, <varname>R</varname>, + <varname>L</varname>, <varname>t</varname>, and + <varname>a</varname> lines.</para> + </refsect2> + + <refsect2> + <title>Age</title> + <para>The date field, when set, is used to decide what files to + delete when cleaning. If a file or directory is older than the + current time minus the age field, it is deleted. The field + format is a series of integers each followed by one of the + following suffixes for the respective time units: + <constant>s</constant>, + <constant>m</constant> or <constant>min</constant>, + <constant>h</constant>, + <constant>d</constant>, + <constant>w</constant>, + <constant>ms</constant>, and + <constant>us</constant>, + meaning seconds, minutes, hours, days, weeks, + milliseconds, and microseconds, respectively. Full names of the time units can + be used too. + </para> + + <para>If multiple integers and units are specified, the time + values are summed. If an integer is given without a unit, + <constant>s</constant> is assumed. + </para> + + <para>When the age is set to zero, the files are cleaned + unconditionally.</para> + + <para>The age field only applies to lines starting with + <varname>d</varname>, <varname>D</varname>, <varname>e</varname>, + <varname>v</varname>, <varname>q</varname>, + <varname>Q</varname>, <varname>C</varname>, <varname>x</varname> + and <varname>X</varname>. If omitted or set to + <literal>-</literal>, no automatic clean-up is done.</para> + + <para>If the age field starts with a tilde character + <literal>~</literal>, the clean-up is only applied to files and + directories one level inside the directory specified, but not + the files and directories immediately inside it.</para> + </refsect2> + + <refsect2> + <title>Argument</title> + + <para>For <varname>L</varname> lines determines the destination + path of the symlink. For <varname>c</varname> and + <varname>b</varname>, determines the major/minor of the device + node, with major and minor formatted as integers, separated by + <literal>:</literal>, e.g. <literal>1:3</literal>. For + <varname>f</varname>, <varname>F</varname>, and + <varname>w</varname>, the argument may be used to specify a short string that + is written to the file, suffixed by a newline. For + <varname>C</varname>, specifies the source file or + directory. For <varname>t</varname> and <varname>T</varname>, + determines extended attributes to be set. For + <varname>a</varname> and <varname>A</varname>, determines ACL + attributes to be set. For <varname>h</varname> and + <varname>H</varname>, determines the file attributes to + set. Ignored for all other lines.</para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <example> + <title>Create directories with specific mode and ownership</title> + <para> + <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs two directories created at boot with specific modes and ownership:</para> + + <programlisting># /usr/lib/tmpfiles.d/screen.conf +d /run/screens 1777 root screen 10d +d /run/uscreens 0755 root screen 10d12h +</programlisting> + + <para>Contents of <filename>/run/screens</filename> and /run/uscreens will + cleaned up after 10 and 10½ days, respectively.</para> + </example> + + <example> + <title>Create a directory with a SMACK attribute</title> + <programlisting>D /run/cups - - - - +t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" + </programlisting> + + <para>The direcory will be owned by root and have default mode. It's contents are + not subject to time based cleanup, but will be obliterated when + <command>systemd-tmpfiles --remove</command> runs.</para> + </example> + + <example> + <title>Create a directory and prevent its contents from cleanup</title> + <para> + <citerefentry><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + needs a directory created at boot with specific mode and ownership and its content + should be preserved from the automatic cleanup applied to the contents of + <filename>/var/tmp</filename>:</para> + + <programlisting># /usr/lib/tmpfiles.d/tmp.conf +d /var/tmp 1777 root root 30d +</programlisting> + + <programlisting># /usr/lib/tmpfiles.d/abrt.conf +d /var/tmp/abrt 0755 abrt abrt - +</programlisting> + </example> + + <example> + <title>Apply clean up during boot and based on time</title> + + <programlisting># /usr/lib/tmpfiles.d/dnf.conf +r! /var/cache/dnf/*/*/download_lock.pid +r! /var/cache/dnf/*/*/metadata_lock.pid +r! /var/lib/dnf/rpmdb_lock.pid +e /var/chache/dnf/ - - - 30d +</programlisting> + + <para>The lock files will be removed during boot. Any files and directories in + <filename>/var/chache/dnf/</filename> will be removed after they have not been + accessed in 30 days.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/user-system-options.xml b/src/manpages/user-system-options.xml new file mode 100644 index 0000000000..8616c54249 --- /dev/null +++ b/src/manpages/user-system-options.xml @@ -0,0 +1,50 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<variablelist> + <varlistentry id='user'> + <term><option>--user</option></term> + + <listitem id='user-text'> + <para>Talk to the service manager of the calling user, + rather than the service manager of the system.</para> + </listitem> + </varlistentry> + + <varlistentry id='system'> + <term><option>--system</option></term> + + <listitem id='system-text'> + <para>Talk to the service manager of the system. This is the + implied default.</para> + </listitem> + </varlistentry> + + <varlistentry id='host'> + <term><option>-H</option></term> + <term><option>--host=</option></term> + + <listitem id='host-text'> + <para>Execute the operation remotely. Specify a hostname, or a + username and hostname separated by <literal>@</literal>, to + connect to. The hostname may optionally be suffixed by a + container name, separated by <literal>:</literal>, which + connects directly to a specific container on the specified + host. This will use SSH to talk to the remote machine manager + instance. Container names may be enumerated with + <command>machinectl -H + <replaceable>HOST</replaceable></command>.</para> + </listitem> + </varlistentry> + + <varlistentry id='machine'> + <term><option>-M</option></term> + <term><option>--machine=</option></term> + + <listitem id='machine-text'> + <para>Execute operation on a local container. Specify a + container name to connect to.</para> + </listitem> + </varlistentry> +</variablelist> diff --git a/src/manpages/vconsole.conf.xml b/src/manpages/vconsole.conf.xml new file mode 100644 index 0000000000..27196d44e9 --- /dev/null +++ b/src/manpages/vconsole.conf.xml @@ -0,0 +1,139 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="vconsole.conf" conditional='ENABLE_VCONSOLE'> + <refentryinfo> + <title>vconsole.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>vconsole.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>vconsole.conf</refname> + <refpurpose>Configuration file for the virtual console</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/vconsole.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/vconsole.conf</filename> file configures + the virtual console, i.e. keyboard mapping and console font. It is + applied at boot by + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>The basic file format of the + <filename>vconsole.conf</filename> is a newline-separated list of + environment-like shell-compatible variable assignments. It is + possible to source the configuration from shell scripts, however, + beyond mere variable assignments no shell features are supported, + allowing applications to read the file without implementing a + shell compatible execution engine.</para> + + <para>Note that the kernel command line options + <varname>vconsole.keymap=</varname>, + <varname>vconsole.keymap.toggle=</varname>, + <varname>vconsole.font=</varname>, + <varname>vconsole.font.map=</varname>, + <varname>vconsole.font.unimap=</varname> may be used + to override the console settings at boot.</para> + + <para>Depending on the operating system other configuration files + might be checked for configuration of the virtual console as well, + however only as fallback.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><varname>KEYMAP=</varname></term> + <term><varname>KEYMAP_TOGGLE=</varname></term> + + <listitem><para>Configures the key mapping table for the + keyboard. <varname>KEYMAP=</varname> defaults to + <literal>us</literal> if not set. The + <varname>KEYMAP_TOGGLE=</varname> can be used to configure a + second toggle keymap and is by default + unset.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FONT=</varname></term> + <term><varname>FONT_MAP=</varname></term> + <term><varname>FONT_UNIMAP=</varname></term> + + <listitem><para>Configures the console font, the console map + and the unicode font map.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German keyboard and console</title> + + <para><filename>/etc/vconsole.conf</filename>:</para> + + <programlisting>KEYMAP=de-latin1 +FONT=eurlatgr</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/zsh-completion/_sd_hosts_or_user_at_host b/src/zsh-completion/_sd_hosts_or_user_at_host new file mode 100644 index 0000000000..282f7328e4 --- /dev/null +++ b/src/zsh-completion/_sd_hosts_or_user_at_host @@ -0,0 +1,5 @@ +#autoload + +_alternative \ + 'users-hosts:: _user_at_host' \ + 'hosts:: _hosts' diff --git a/src/zsh-completion/_sd_machines b/src/zsh-completion/_sd_machines new file mode 100644 index 0000000000..a0039ee0f8 --- /dev/null +++ b/src/zsh-completion/_sd_machines @@ -0,0 +1,13 @@ +#autoload +__get_machines () { + machinectl --full --no-legend --no-pager list | {while read -r a b; do echo $a; done;}; +} + +local -a _machines +_machines=("${(fo)$(__get_machines)}") +typeset -U _machines +if [[ -n "$_machines" ]]; then + _describe 'machines' _machines +else + _message 'no machines' +fi diff --git a/src/zsh-completion/_sd_outputmodes b/src/zsh-completion/_sd_outputmodes new file mode 100644 index 0000000000..3836f79b73 --- /dev/null +++ b/src/zsh-completion/_sd_outputmodes @@ -0,0 +1,5 @@ +#autoload + +local -a _output_opts +_output_opts=(short short-iso short-precise short-monotonic verbose export json json-pretty json-sse cat) +_describe -t output 'output mode' _output_opts || compadd "$@" diff --git a/src/zsh-completion/_sd_unit_files b/src/zsh-completion/_sd_unit_files new file mode 100644 index 0000000000..3e7a4ee803 --- /dev/null +++ b/src/zsh-completion/_sd_unit_files @@ -0,0 +1,9 @@ +#autoload + +_sd_unit_files() { + local files expl + files=( '*:files:->files' ) + + _description files expl 'unit file' + _files "$expl[@]" -g '*.(automount|busname|device|mount|path|service|socket|swap|target|timer)' +} |