diff options
Diffstat (limited to 'src/grp-hostname/hostnamectl')
| l--------- | src/grp-hostname/hostnamectl/GNUmakefile | 1 | ||||
| -rw-r--r-- | src/grp-hostname/hostnamectl/Makefile | 44 | ||||
| -rw-r--r-- | src/grp-hostname/hostnamectl/hostnamectl.c | 531 | ||||
| -rw-r--r-- | src/grp-hostname/hostnamectl/hostnamectl.completion.bash | 64 | ||||
| -rw-r--r-- | src/grp-hostname/hostnamectl/hostnamectl.completion.zsh | 80 | ||||
| -rw-r--r-- | src/grp-hostname/hostnamectl/hostnamectl.xml | 247 |
6 files changed, 967 insertions, 0 deletions
diff --git a/src/grp-hostname/hostnamectl/GNUmakefile b/src/grp-hostname/hostnamectl/GNUmakefile new file mode 120000 index 0000000000..95e5924740 --- /dev/null +++ b/src/grp-hostname/hostnamectl/GNUmakefile @@ -0,0 +1 @@ +../../../GNUmakefile
\ No newline at end of file diff --git a/src/grp-hostname/hostnamectl/Makefile b/src/grp-hostname/hostnamectl/Makefile new file mode 100644 index 0000000000..c728acce7b --- /dev/null +++ b/src/grp-hostname/hostnamectl/Makefile @@ -0,0 +1,44 @@ +# -*- Mode: makefile; indent-tabs-mode: t -*- +# +# This file is part of systemd. +# +# Copyright 2010-2012 Lennart Poettering +# Copyright 2010-2012 Kay Sievers +# Copyright 2013 Zbigniew Jędrzejewski-Szmek +# Copyright 2013 David Strauss +# Copyright 2016 Luke Shumaker +# +# 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/>. +include $(dir $(lastword $(MAKEFILE_LIST)))/../../../config.mk +include $(topsrcdir)/build-aux/Makefile.head.mk + +ifneq ($(ENABLE_HOSTNAMED),) + +hostnamectl_SOURCES = \ + src/hostname/hostnamectl.c + +hostnamectl_LDADD = \ + libsystemd-shared.la + +bin_PROGRAMS += \ + hostnamectl + +dist_bashcompletion_data += \ + shell-completion/bash/hostnamectl + +dist_zshcompletion_data += \ + shell-completion/zsh/_hostnamectl +endif # ENABLE_HOSTNAMED + +include $(topsrcdir)/build-aux/Makefile.tail.mk diff --git a/src/grp-hostname/hostnamectl/hostnamectl.c b/src/grp-hostname/hostnamectl/hostnamectl.c new file mode 100644 index 0000000000..d6da61879b --- /dev/null +++ b/src/grp-hostname/hostnamectl/hostnamectl.c @@ -0,0 +1,531 @@ +/*** + 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/>. +***/ + +#include <getopt.h> +#include <locale.h> +#include <stdbool.h> +#include <stdlib.h> +#include <string.h> + +#include <systemd/sd-bus.h> +#include <systemd/sd-id128.h> + +#include "sd-bus/bus-error.h" +#include "sd-bus/bus-util.h" +#include "systemd-basic/alloc-util.h" +#include "systemd-basic/architecture.h" +#include "systemd-basic/hostname-util.h" +#include "systemd-basic/util.h" +#include "systemd-shared/spawn-polkit-agent.h" + +static bool arg_ask_password = true; +static BusTransport arg_transport = BUS_TRANSPORT_LOCAL; +static char *arg_host = NULL; +static bool arg_transient = false; +static bool arg_pretty = false; +static bool arg_static = false; + +static void polkit_agent_open_if_enabled(void) { + + /* Open the polkit agent as a child process if necessary */ + if (!arg_ask_password) + return; + + if (arg_transport != BUS_TRANSPORT_LOCAL) + return; + + polkit_agent_open(); +} + +typedef struct StatusInfo { + char *hostname; + char *static_hostname; + char *pretty_hostname; + char *icon_name; + char *chassis; + char *deployment; + char *location; + char *kernel_name; + char *kernel_release; + char *os_pretty_name; + char *os_cpe_name; + char *virtualization; + char *architecture; +} StatusInfo; + +static void print_status_info(StatusInfo *i) { + sd_id128_t mid = {}, bid = {}; + int r; + + assert(i); + + printf(" Static hostname: %s\n", strna(i->static_hostname)); + + if (!isempty(i->pretty_hostname) && + !streq_ptr(i->pretty_hostname, i->static_hostname)) + printf(" Pretty hostname: %s\n", i->pretty_hostname); + + if (!isempty(i->hostname) && + !streq_ptr(i->hostname, i->static_hostname)) + printf("Transient hostname: %s\n", i->hostname); + + if (!isempty(i->icon_name)) + printf(" Icon name: %s\n", + strna(i->icon_name)); + + if (!isempty(i->chassis)) + printf(" Chassis: %s\n", + strna(i->chassis)); + + if (!isempty(i->deployment)) + printf(" Deployment: %s\n", i->deployment); + + if (!isempty(i->location)) + printf(" Location: %s\n", i->location); + + r = sd_id128_get_machine(&mid); + if (r >= 0) + printf(" Machine ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(mid)); + + r = sd_id128_get_boot(&bid); + if (r >= 0) + printf(" Boot ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(bid)); + + if (!isempty(i->virtualization)) + printf(" Virtualization: %s\n", i->virtualization); + + if (!isempty(i->os_pretty_name)) + printf(" Operating System: %s\n", i->os_pretty_name); + + if (!isempty(i->os_cpe_name)) + printf(" CPE OS Name: %s\n", i->os_cpe_name); + + if (!isempty(i->kernel_name) && !isempty(i->kernel_release)) + printf(" Kernel: %s %s\n", i->kernel_name, i->kernel_release); + + if (!isempty(i->architecture)) + printf(" Architecture: %s\n", i->architecture); + +} + +static int show_one_name(sd_bus *bus, const char* attr) { + _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL; + _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; + const char *s; + int r; + + r = sd_bus_get_property( + bus, + "org.freedesktop.hostname1", + "/org/freedesktop/hostname1", + "org.freedesktop.hostname1", + attr, + &error, &reply, "s"); + if (r < 0) { + log_error("Could not get property: %s", bus_error_message(&error, -r)); + return r; + } + + r = sd_bus_message_read(reply, "s", &s); + if (r < 0) + return bus_log_parse_error(r); + + printf("%s\n", s); + + return 0; +} + +static int show_all_names(sd_bus *bus) { + StatusInfo info = {}; + + static const struct bus_properties_map hostname_map[] = { + { "Hostname", "s", NULL, offsetof(StatusInfo, hostname) }, + { "StaticHostname", "s", NULL, offsetof(StatusInfo, static_hostname) }, + { "PrettyHostname", "s", NULL, offsetof(StatusInfo, pretty_hostname) }, + { "IconName", "s", NULL, offsetof(StatusInfo, icon_name) }, + { "Chassis", "s", NULL, offsetof(StatusInfo, chassis) }, + { "Deployment", "s", NULL, offsetof(StatusInfo, deployment) }, + { "Location", "s", NULL, offsetof(StatusInfo, location) }, + { "KernelName", "s", NULL, offsetof(StatusInfo, kernel_name) }, + { "KernelRelease", "s", NULL, offsetof(StatusInfo, kernel_release) }, + { "OperatingSystemPrettyName", "s", NULL, offsetof(StatusInfo, os_pretty_name) }, + { "OperatingSystemCPEName", "s", NULL, offsetof(StatusInfo, os_cpe_name) }, + {} + }; + + static const struct bus_properties_map manager_map[] = { + { "Virtualization", "s", NULL, offsetof(StatusInfo, virtualization) }, + { "Architecture", "s", NULL, offsetof(StatusInfo, architecture) }, + {} + }; + + int r; + + r = bus_map_all_properties(bus, + "org.freedesktop.hostname1", + "/org/freedesktop/hostname1", + hostname_map, + &info); + if (r < 0) + goto fail; + + bus_map_all_properties(bus, + "org.freedesktop.systemd1", + "/org/freedesktop/systemd1", + manager_map, + &info); + + print_status_info(&info); + +fail: + free(info.hostname); + free(info.static_hostname); + free(info.pretty_hostname); + free(info.icon_name); + free(info.chassis); + free(info.deployment); + free(info.location); + free(info.kernel_name); + free(info.kernel_release); + free(info.os_pretty_name); + free(info.os_cpe_name); + free(info.virtualization); + free(info.architecture); + + return r; +} + +static int show_status(sd_bus *bus, char **args, unsigned n) { + assert(args); + + if (arg_pretty || arg_static || arg_transient) { + const char *attr; + + if (!!arg_static + !!arg_pretty + !!arg_transient > 1) { + log_error("Cannot query more than one name type at a time"); + return -EINVAL; + } + + attr = arg_pretty ? "PrettyHostname" : + arg_static ? "StaticHostname" : "Hostname"; + + return show_one_name(bus, attr); + } else + return show_all_names(bus); +} + +static int set_simple_string(sd_bus *bus, const char *method, const char *value) { + _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; + int r = 0; + + polkit_agent_open_if_enabled(); + + r = sd_bus_call_method( + bus, + "org.freedesktop.hostname1", + "/org/freedesktop/hostname1", + "org.freedesktop.hostname1", + method, + &error, NULL, + "sb", value, arg_ask_password); + if (r < 0) + log_error("Could not set property: %s", bus_error_message(&error, -r)); + return r; +} + +static int set_hostname(sd_bus *bus, char **args, unsigned n) { + _cleanup_free_ char *h = NULL; + const char *hostname = args[1]; + int r; + + assert(args); + assert(n == 2); + + if (!arg_pretty && !arg_static && !arg_transient) + arg_pretty = arg_static = arg_transient = true; + + if (arg_pretty) { + const char *p; + + /* If the passed hostname is already valid, then assume the user doesn't know anything about pretty + * hostnames, so let's unset the pretty hostname, and just set the passed hostname as static/dynamic + * hostname. */ + if (arg_static && hostname_is_valid(hostname, true)) + p = ""; /* No pretty hostname (as it is redundant), just a static one */ + else + p = hostname; /* Use the passed name as pretty hostname */ + + r = set_simple_string(bus, "SetPrettyHostname", p); + if (r < 0) + return r; + + /* Now that we set the pretty hostname, let's clean up the parameter and use that as static + * hostname. If the hostname was already valid as static hostname, this will only chop off the trailing + * dot if there is one. If it was not valid, then it will be made fully valid by truncating, dropping + * multiple dots, and dropping weird chars. Note that we clean the name up only if we also are + * supposed to set the pretty name. If the pretty name is not being set we assume the user knows what + * he does and pass the name as-is. */ + h = strdup(hostname); + if (!h) + return log_oom(); + + hostname = hostname_cleanup(h); /* Use the cleaned up name as static hostname */ + } + + if (arg_static) { + r = set_simple_string(bus, "SetStaticHostname", hostname); + if (r < 0) + return r; + } + + if (arg_transient) { + r = set_simple_string(bus, "SetHostname", hostname); + if (r < 0) + return r; + } + + return 0; +} + +static int set_icon_name(sd_bus *bus, char **args, unsigned n) { + assert(args); + assert(n == 2); + + return set_simple_string(bus, "SetIconName", args[1]); +} + +static int set_chassis(sd_bus *bus, char **args, unsigned n) { + assert(args); + assert(n == 2); + + return set_simple_string(bus, "SetChassis", args[1]); +} + +static int set_deployment(sd_bus *bus, char **args, unsigned n) { + assert(args); + assert(n == 2); + + return set_simple_string(bus, "SetDeployment", args[1]); +} + +static int set_location(sd_bus *bus, char **args, unsigned n) { + assert(args); + assert(n == 2); + + return set_simple_string(bus, "SetLocation", args[1]); +} + +static void help(void) { + printf("%s [OPTIONS...] COMMAND ...\n\n" + "Query or change system hostname.\n\n" + " -h --help Show this help\n" + " --version Show package version\n" + " --no-ask-password Do not prompt for password\n" + " -H --host=[USER@]HOST Operate on remote host\n" + " -M --machine=CONTAINER Operate on local container\n" + " --transient Only set transient hostname\n" + " --static Only set static hostname\n" + " --pretty Only set pretty hostname\n\n" + "Commands:\n" + " status Show current hostname settings\n" + " set-hostname NAME Set system hostname\n" + " set-icon-name NAME Set icon name for host\n" + " set-chassis NAME Set chassis type for host\n" + " set-deployment NAME Set deployment environment for host\n" + " set-location NAME Set location for host\n" + , program_invocation_short_name); +} + +static int parse_argv(int argc, char *argv[]) { + + enum { + ARG_VERSION = 0x100, + ARG_NO_ASK_PASSWORD, + ARG_TRANSIENT, + ARG_STATIC, + ARG_PRETTY + }; + + static const struct option options[] = { + { "help", no_argument, NULL, 'h' }, + { "version", no_argument, NULL, ARG_VERSION }, + { "transient", no_argument, NULL, ARG_TRANSIENT }, + { "static", no_argument, NULL, ARG_STATIC }, + { "pretty", no_argument, NULL, ARG_PRETTY }, + { "host", required_argument, NULL, 'H' }, + { "machine", required_argument, NULL, 'M' }, + { "no-ask-password", no_argument, NULL, ARG_NO_ASK_PASSWORD }, + {} + }; + + int c; + + assert(argc >= 0); + assert(argv); + + while ((c = getopt_long(argc, argv, "hH:M:", options, NULL)) >= 0) + + switch (c) { + + case 'h': + help(); + return 0; + + case ARG_VERSION: + return version(); + + case 'H': + arg_transport = BUS_TRANSPORT_REMOTE; + arg_host = optarg; + break; + + case 'M': + arg_transport = BUS_TRANSPORT_MACHINE; + arg_host = optarg; + break; + + case ARG_TRANSIENT: + arg_transient = true; + break; + + case ARG_PRETTY: + arg_pretty = true; + break; + + case ARG_STATIC: + arg_static = true; + break; + + case ARG_NO_ASK_PASSWORD: + arg_ask_password = false; + break; + + case '?': + return -EINVAL; + + default: + assert_not_reached("Unhandled option"); + } + + return 1; +} + +static int hostnamectl_main(sd_bus *bus, int argc, char *argv[]) { + + static const struct { + const char* verb; + const enum { + MORE, + LESS, + EQUAL + } argc_cmp; + const int argc; + int (* const dispatch)(sd_bus *bus, char **args, unsigned n); + } verbs[] = { + { "status", LESS, 1, show_status }, + { "set-hostname", EQUAL, 2, set_hostname }, + { "set-icon-name", EQUAL, 2, set_icon_name }, + { "set-chassis", EQUAL, 2, set_chassis }, + { "set-deployment", EQUAL, 2, set_deployment }, + { "set-location", EQUAL, 2, set_location }, + }; + + int left; + unsigned i; + + assert(argc >= 0); + assert(argv); + + left = argc - optind; + + if (left <= 0) + /* Special rule: no arguments means "status" */ + i = 0; + else { + if (streq(argv[optind], "help")) { + help(); + return 0; + } + + for (i = 0; i < ELEMENTSOF(verbs); i++) + if (streq(argv[optind], verbs[i].verb)) + break; + + if (i >= ELEMENTSOF(verbs)) { + log_error("Unknown operation %s", argv[optind]); + return -EINVAL; + } + } + + switch (verbs[i].argc_cmp) { + + case EQUAL: + if (left != verbs[i].argc) { + log_error("Invalid number of arguments."); + return -EINVAL; + } + + break; + + case MORE: + if (left < verbs[i].argc) { + log_error("Too few arguments."); + return -EINVAL; + } + + break; + + case LESS: + if (left > verbs[i].argc) { + log_error("Too many arguments."); + return -EINVAL; + } + + break; + + default: + assert_not_reached("Unknown comparison operator."); + } + + return verbs[i].dispatch(bus, argv + optind, left); +} + +int main(int argc, char *argv[]) { + _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; + int r; + + setlocale(LC_ALL, ""); + log_parse_environment(); + log_open(); + + r = parse_argv(argc, argv); + if (r <= 0) + goto finish; + + r = bus_connect_transport(arg_transport, arg_host, false, &bus); + if (r < 0) { + log_error_errno(r, "Failed to create bus connection: %m"); + goto finish; + } + + r = hostnamectl_main(bus, argc, argv); + +finish: + return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS; +} diff --git a/src/grp-hostname/hostnamectl/hostnamectl.completion.bash b/src/grp-hostname/hostnamectl/hostnamectl.completion.bash new file mode 100644 index 0000000000..6a252188ea --- /dev/null +++ b/src/grp-hostname/hostnamectl/hostnamectl.completion.bash @@ -0,0 +1,64 @@ +# hostnamectl(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/>. + +__contains_word () { + local w word=$1; shift + for w in "$@"; do + [[ $w = "$word" ]] && return + done +} + +_hostnamectl() { + local i verb comps + local cur=${COMP_WORDS[COMP_CWORD]} prev=${COMP_WORDS[COMP_CWORD-1]} + local OPTS='-h --help --version --transient --static --pretty + --no-ask-password -H --host --machine' + + if [[ $cur = -* ]]; then + COMPREPLY=( $(compgen -W '${OPTS[*]}' -- "$cur") ) + return 0 + fi + + local -A VERBS=( + [STANDALONE]='status' + [ICONS]='set-icon-name' + [NAME]='set-hostname set-deployment set-location' + [CHASSIS]='set-chassis' + ) + + for ((i=0; i < COMP_CWORD; i++)); do + if __contains_word "${COMP_WORDS[i]}" ${VERBS[*]}; then + verb=${COMP_WORDS[i]} + break + fi + done + + if [[ -z $verb ]]; then + comps=${VERBS[*]} + elif __contains_word "$verb" ${VERBS[CHASSIS]}; then + comps='desktop laptop server tablet handset watch embedded vm container' + elif __contains_word "$verb" ${VERBS[STANDALONE]} ${VERBS[ICONS]} ${VERBS[NAME]}; then + comps='' + fi + + COMPREPLY=( $(compgen -W '$comps' -- "$cur") ) + return 0 +} + +complete -F _hostnamectl hostnamectl diff --git a/src/grp-hostname/hostnamectl/hostnamectl.completion.zsh b/src/grp-hostname/hostnamectl/hostnamectl.completion.zsh new file mode 100644 index 0000000000..7528e0649d --- /dev/null +++ b/src/grp-hostname/hostnamectl/hostnamectl.completion.zsh @@ -0,0 +1,80 @@ +#compdef hostnamectl + +_hostnamectl_set-hostname() { + if (( CURRENT <= 3 )); then + _message "new hostname" + else + _message "no more options" + fi +} + +_hostnamectl_set-icon-name() { + if (( CURRENT <= 3 )); then + _message "new icon name" + else + _message "no more options" + fi +} + +_hostnamectl_set-chassis() { + if (( CURRENT <= 3 )); then + _chassis=( desktop laptop server tablet handset watch embedded vm container ) + _describe chassis _chassis + else + _message "no more options" + fi +} + +_hostnamectl_set-deployment() { + if (( CURRENT <= 3 )); then + _message "new environment" + else + _message "no more options" + fi +} + +_hostnamectl_set-location() { + if (( CURRENT <= 3 )); then + _message "new location" + else + _message "no more options" + fi +} + +_hostnamectl_command() { + local -a _hostnamectl_cmds + _hostnamectl_cmds=( + "status:Show current hostname settings" + "set-hostname:Set system hostname" + "set-icon-name:Set icon name for host" + "set-chassis:Set chassis type for host" + "set-deployment:Set deployment environment for host" + "set-location:Set location for host" + ) + if (( CURRENT == 1 )); then + _describe -t commands 'hostnamectl commands' _hostnamectl_cmds || compadd "$@" + else + local curcontext="$curcontext" + cmd="${${_hostnamectl_cmds[(r)$words[1]:*]%%:*}}" + if (( $#cmd )); then + if [[ $cmd == status ]]; then + _message "no options" + else + _hostnamectl_$cmd + fi + else + _message "unknown hostnamectl command: $words[1]" + fi + fi +} + +_arguments -s \ + {-h,--help}'[Show this help]' \ + '--version[Show package version]' \ + '--transient[Only set transient hostname]' \ + '--static[Only set static hostname]' \ + '--pretty[Only set pretty hostname]' \ + '--no-ask-password[Do not prompt for password]' \ + {-H+,--host=}'[Operate on remote host]:userathost:_sd_hosts_or_user_at_host' \ + {-M+,--machine=}'[Operate on local container]:machines:_sd_machines' \ + '*::hostnamectl commands:_hostnamectl_command' diff --git a/src/grp-hostname/hostnamectl/hostnamectl.xml b/src/grp-hostname/hostnamectl/hostnamectl.xml new file mode 100644 index 0000000000..9e1b593e6d --- /dev/null +++ b/src/grp-hostname/hostnamectl/hostnamectl.xml @@ -0,0 +1,247 @@ +<?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="hostnamectl" conditional='ENABLE_HOSTNAMED' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>hostnamectl</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>hostnamectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostnamectl</refname> + <refpurpose>Control the system hostname</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>hostnamectl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>hostnamectl</command> may be used to query and + change the system hostname and related settings.</para> + + <para>This tool distinguishes three different hostnames: the + high-level "pretty" hostname which might include all kinds of + special characters (e.g. "Lennart's Laptop"), the static hostname + which is used to initialize the kernel hostname at boot (e.g. + "lennarts-laptop"), and the transient hostname which is a fallback + value received from network configuration. If a static hostname is + set, and is valid (something other than localhost), then the + transient hostname is not used.</para> + + <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and + transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at + maximum (the latter being a Linux limitation).</para> + + <para>The static hostname is stored in + <filename>/etc/hostname</filename>, see + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information. The pretty hostname, chassis type, and icon + name are stored in <filename>/etc/machine-info</filename>, see + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the system host name for mounted (but not booted) + system images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--static</option></term> + <term><option>--transient</option></term> + <term><option>--pretty</option></term> + + <listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these + switches is specified, <command>hostnamectl</command> will print out just this selected hostname.</para> + + <para>If used with <command>set-hostname</command>, only the selected hostname(s) will be updated. When more + than one of these switches are specified, all the specified hostnames will be updated. </para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current system + hostname and related + information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-hostname <replaceable>NAME</replaceable></command></term> + + <listitem><para>Set the system hostname to <replaceable>NAME</replaceable>. By default, this will alter the + pretty, the static, and the transient hostname alike; however, if one or more of <option>--static</option>, + <option>--transient</option>, <option>--pretty</option> are used, only the selected hostnames are changed. If + the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be + simplified in regards to the character set used before the latter are updated. This is done by removing special + characters and spaces. This ensures that the pretty and the static hostname are always closely related while + still following the validity rules of the specific name. This simplification of the hostname string is not done + if only the transient and/or static host names are set, and the pretty host name is left untouched.</para> + + <para>Pass the empty string <literal></literal> as the + hostname to reset the selected hostnames to their default + (usually <literal>localhost</literal>).</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-icon-name <replaceable>NAME</replaceable></command></term> + + <listitem><para>Set the system icon name to + <replaceable>NAME</replaceable>. The icon name is used by some + graphical applications to visualize this host. The icon name + should follow the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon + Naming Specification</ulink>.</para> + + <para>Pass an empty string to reset the icon name to the + default value, which is determined from chassis type (see + below) and possibly other parameters.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-chassis <replaceable>TYPE</replaceable></command></term> + + <listitem><para>Set the chassis type to + <replaceable>TYPE</replaceable>. The chassis type is used by + some graphical applications to visualize the host or alter + user interaction. 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>, + <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.</para> + + <para>Pass an empty string to reset the chassis type to the + default value which is determined from the firmware and + possibly other parameters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term> + + <listitem><para>Set the deployment environment description. + <replaceable>ENVIRONMENT</replaceable> must be a single word + without any control characters. One of the following is + suggested: + <literal>development</literal>, + <literal>integration</literal>, + <literal>staging</literal>, + <literal>production</literal>. + </para> + + <para>Pass an empty string to reset to the default empty + value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>set-location <replaceable>LOCATION</replaceable></command></term> + + <listitem><para>Set the location string for the system, if it + is known. <replaceable>LOCATION</replaceable> should be a + human-friendly, free-form string describing the physical + location of the system, if it is known and applicable. This + may be as generic as <literal>Berlin, Germany</literal> or as + specific as <literal>Left Rack, 2nd Shelf</literal>.</para> + + <para>Pass an empty string to reset to the default empty + value.</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>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</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> |