Debian Codegraph @

upstream/debian-trixie/man1/timedatectl.1

raw
1 '\" t
2 .TH "TIMEDATECTL" "1" "" "systemd 257.13" "timedatectl"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 timedatectl \- Control the system time and date
24 .SH "SYNOPSIS"
25 .HP \w'\fBtimedatectl\fR\ 'u
26 \fBtimedatectl\fR [OPTIONS...] {COMMAND}
27 .SH "DESCRIPTION"
28 .PP
29 \fBtimedatectl\fR
30 may be used to query and change the system clock and its settings, and enable or disable time synchronization services\&.
31 .PP
32 Use
33 \fBsystemd-firstboot\fR(1)
34 to initialize the system time zone for mounted (but not booted) system images\&.
35 .PP
36 \fBtimedatectl\fR
37 may be used to show the current status of time synchronization services, for example
38 \fBsystemd-timesyncd.service\fR(8)\&.
39 .SH "COMMANDS"
40 .PP
41 The following commands are understood:
42 .PP
43 \fBstatus\fR
44 .RS 4
45 Show current settings of the system clock and RTC, including whether network time synchronization is active\&. If no command is specified, this is the implied default\&.
46 .sp
47 Added in version 195\&.
48 .RE
49 .PP
50 \fBshow\fR
51 .RS 4
52 Show the same information as
53 \fBstatus\fR, but in machine readable form\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
54 \fBstatus\fR
55 if you are looking for formatted human\-readable output\&.
56 .sp
57 By default, empty properties are suppressed\&. Use
58 \fB\-\-all\fR
59 to show those too\&. To select specific properties to show, use
60 \fB\-\-property=\fR\&.
61 .sp
62 Added in version 239\&.
63 .RE
64 .PP
65 \fBset\-time [TIME]\fR
66 .RS 4
67 Set the system clock to the specified timestamp\&. This will also update the RTC time accordingly\&. The timestamp may be specified in the format
68 "2012\-10\-30 18:17:16"\&. See
69 \fBsystemd.time\fR(7)
70 for more details about acceptable timestamp format\&.
71 .sp
72 Added in version 195\&.
73 .RE
74 .PP
75 \fBset\-timezone [TIMEZONE]\fR
76 .RS 4
77 Set the system time zone to the specified value\&. Available timezones can be listed with
78 \fBlist\-timezones\fR\&. If the RTC is configured to be in the local time, this will also update the RTC time\&. This call will alter the
79 /etc/localtime
80 symlink\&. See
81 \fBlocaltime\fR(5)
82 for more information\&.
83 .sp
84 Added in version 195\&.
85 .RE
86 .PP
87 \fBlist\-timezones\fR
88 .RS 4
89 List available time zones, one per line\&. Entries from the list can be set as the system timezone with
90 \fBset\-timezone\fR\&.
91 .sp
92 Added in version 195\&.
93 .RE
94 .PP
95 \fBset\-local\-rtc [BOOL]\fR
96 .RS 4
97 Takes a boolean argument\&. If
98 "0", the system is configured to maintain the RTC in universal time\&. If
99 "1", it will maintain the RTC in local time instead\&. Note that maintaining the RTC in the local timezone is not fully supported and will create various problems with time zone changes and daylight saving adjustments\&. If at all possible, keep the RTC in UTC mode\&. Note that invoking this will also synchronize the RTC from the system clock, unless
100 \fB\-\-adjust\-system\-clock\fR
101 is passed (see above)\&. This command will change the 3rd line of
102 /etc/adjtime, as documented in
103 \fBhwclock\fR(8)\&.
104 .sp
105 Added in version 195\&.
106 .RE
107 .PP
108 \fBset\-ntp [BOOL]\fR
109 .RS 4
110 Takes a boolean argument\&. Controls whether network time synchronization is active and enabled (if available)\&. If the argument is true, this enables and starts the first existing network synchronization service\&. If the argument is false, then this disables and stops the known network synchronization services\&. The way that the list of services is built is described in
111 \fBsystemd-timedated.service\fR(8)\&.
112 .sp
113 Added in version 195\&.
114 .RE
115 .SS "systemd\-timesyncd Commands"
116 .PP
117 The following commands are specific to
118 \fBsystemd-timesyncd.service\fR(8)\&.
119 .PP
120 \fBtimesync\-status\fR
121 .RS 4
122 Show current status of
123 \fBsystemd-timesyncd.service\fR(8)\&. If
124 \fB\-\-monitor\fR
125 is specified, then this will monitor the status updates\&.
126 .sp
127 Added in version 239\&.
128 .RE
129 .PP
130 \fBshow\-timesync\fR
131 .RS 4
132 Show the same information as
133 \fBtimesync\-status\fR, but in machine readable form\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
134 \fBtimesync\-status\fR
135 if you are looking for formatted human\-readable output\&.
136 .sp
137 By default, empty properties are suppressed\&. Use
138 \fB\-\-all\fR
139 to show those too\&. To select specific properties to show, use
140 \fB\-\-property=\fR\&.
141 .sp
142 Added in version 239\&.
143 .RE
144 .PP
145 \fBntp\-servers \fR\fB\fIINTERFACE\fR\fR\fB \fR\fB\fISERVER\fR\fR\fB\&...\fR
146 .RS 4
147 Set the interface specific NTP servers\&. This command can be used only when the interface is managed by
148 \fBsystemd\-networkd\fR\&.
149 .sp
150 Added in version 243\&.
151 .RE
152 .PP
153 \fBrevert \fR\fB\fIINTERFACE\fR\fR
154 .RS 4
155 Revert the interface specific NTP servers\&. This command can be used only when the interface is managed by
156 \fBsystemd\-networkd\fR\&.
157 .sp
158 Added in version 243\&.
159 .RE
160 .SH "OPTIONS"
161 .PP
162 The following options are understood:
163 .PP
164 \fB\-\-adjust\-system\-clock\fR
165 .RS 4
166 If
167 \fBset\-local\-rtc\fR
168 is invoked and this option is passed, the system clock is synchronized from the RTC again, taking the new setting into account\&. Otherwise, the RTC is synchronized from the system clock\&.
169 .sp
170 Added in version 195\&.
171 .RE
172 .PP
173 \fB\-\-monitor\fR
174 .RS 4
175 If
176 \fBtimesync\-status\fR
177 is invoked and this option is passed, then
178 \fBtimedatectl\fR
179 monitors the status of
180 \fBsystemd-timesyncd.service\fR(8)
181 and updates the outputs\&. Use
182 Ctrl+C
183 to terminate the monitoring\&.
184 .sp
185 Added in version 239\&.
186 .RE
187 .PP
188 \fB\-a\fR, \fB\-\-all\fR
189 .RS 4
190 When showing properties of
191 \fBsystemd-timesyncd.service\fR(8), show all properties regardless of whether they are set or not\&.
192 .sp
193 Added in version 239\&.
194 .RE
195 .PP
196 \fB\-p\fR, \fB\-\-property=\fR
197 .RS 4
198 When showing properties of
199 \fBsystemd-timesyncd.service\fR(8), limit display to certain properties as specified as argument\&. If not specified, all set properties are shown\&. The argument should be a property name, such as
200 "ServerName"\&. If specified more than once, all properties with the specified names are shown\&.
201 .sp
202 Added in version 239\&.
203 .RE
204 .PP
205 \fB\-\-value\fR
206 .RS 4
207 When printing properties with
208 \fBshow\-timesync\fR, only print the value, and skip the property name and
209 "="\&.
210 .sp
211 Added in version 239\&.
212 .RE
213 .PP
214 \fB\-P\fR
215 .RS 4
216 Equivalent to
217 \fB\-\-value\fR
218 \fB\-\-property=\fR, i\&.e\&. shows the value of the property without the property name or
219 "="\&. Note that using
220 \fB\-P\fR
221 once will also affect all properties listed with
222 \fB\-p\fR/\fB\-\-property=\fR\&.
223 .sp
224 Added in version 256\&.
225 .RE
226 .PP
227 \fB\-H\fR, \fB\-\-host=\fR
228 .RS 4
229 Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
230 "@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
231 ":", and then a container name, separated by
232 "/", 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
233 \fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
234 .RE
235 .PP
236 \fB\-M\fR, \fB\-\-machine=\fR
237 .RS 4
238 Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
239 "@"
240 character\&. If the special string
241 "\&.host"
242 is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
243 "\-\-user \-\-machine=lennart@\&.host")\&. If the
244 "@"
245 syntax is not used, the connection is made as root user\&. If the
246 "@"
247 syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
248 "\&.host"
249 are implied\&.
250 .RE
251 .PP
252 \fB\-\-no\-ask\-password\fR
253 .RS 4
254 Do not query the user for authentication for privileged operations\&.
255 .RE
256 .PP
257 \fB\-h\fR, \fB\-\-help\fR
258 .RS 4
259 Print a short help text and exit\&.
260 .RE
261 .PP
262 \fB\-\-version\fR
263 .RS 4
264 Print a short version string and exit\&.
265 .RE
266 .PP
267 \fB\-\-no\-pager\fR
268 .RS 4
269 Do not pipe output into a pager\&.
270 .RE
271 .SH "EXIT STATUS"
272 .PP
273 On success, 0 is returned, a non\-zero failure code otherwise\&.
274 .SH "ENVIRONMENT"
275 .PP
276 \fI$SYSTEMD_LOG_LEVEL\fR
277 .RS 4
278 The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance)
279 \fBemerg\fR,
280 \fBalert\fR,
281 \fBcrit\fR,
282 \fBerr\fR,
283 \fBwarning\fR,
284 \fBnotice\fR,
285 \fBinfo\fR,
286 \fBdebug\fR, or an integer in the range 0\&...7\&. See
287 \fBsyslog\fR(3)
288 for more information\&. Each value may optionally be prefixed with one of
289 \fBconsole\fR,
290 \fBsyslog\fR,
291 \fBkmsg\fR
292 or
293 \fBjournal\fR
294 followed by a colon to set the maximum log level for that specific log target (e\&.g\&.
295 \fBSYSTEMD_LOG_LEVEL=debug,console:info\fR
296 specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&.
297 .RE
298 .PP
299 \fI$SYSTEMD_LOG_COLOR\fR
300 .RS 4
301 A boolean\&. If true, messages written to the tty will be colored according to priority\&.
302 .sp
303 This setting is only useful when messages are written directly to the terminal, because
304 \fBjournalctl\fR(1)
305 and other tools that display logs will color messages based on the log level on their own\&.
306 .RE
307 .PP
308 \fI$SYSTEMD_LOG_TIME\fR
309 .RS 4
310 A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
311 .sp
312 This setting is only useful when messages are written directly to the terminal or a file, because
313 \fBjournalctl\fR(1)
314 and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
315 .RE
316 .PP
317 \fI$SYSTEMD_LOG_LOCATION\fR
318 .RS 4
319 A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
320 .sp
321 Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
322 .RE
323 .PP
324 \fI$SYSTEMD_LOG_TID\fR
325 .RS 4
326 A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
327 .sp
328 Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
329 .RE
330 .PP
331 \fI$SYSTEMD_LOG_TARGET\fR
332 .RS 4
333 The destination for log messages\&. One of
334 \fBconsole\fR
335 (log to the attached tty),
336 \fBconsole\-prefixed\fR
337 (log to the attached tty but with prefixes encoding the log level and "facility", see
338 \fBsyslog\fR(3),
339 \fBkmsg\fR
340 (log to the kernel circular log buffer),
341 \fBjournal\fR
342 (log to the journal),
343 \fBjournal\-or\-kmsg\fR
344 (log to the journal if available, and to kmsg otherwise),
345 \fBauto\fR
346 (determine the appropriate log target automatically, the default),
347 \fBnull\fR
348 (disable log output)\&.
349 .RE
350 .PP
351 \fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
352 .RS 4
353 Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
354 "true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
355 .RE
356 .PP
357 \fI$SYSTEMD_PAGER\fR, \fI$PAGER\fR
358 .RS 4
359 Pager to use when
360 \fB\-\-no\-pager\fR
361 is not given\&.
362 \fI$SYSTEMD_PAGER\fR
363 is used if set; otherwise
364 \fI$PAGER\fR
365 is used\&. If neither
366 \fI$SYSTEMD_PAGER\fR
367 nor
368 \fI$PAGER\fR
369 are set, a set of well\-known pager implementations is tried in turn, including
370 \fBless\fR(1)
371 and
372 \fBmore\fR(1), until one is found\&. If no pager implementation is discovered, no pager is invoked\&. Setting those environment variables to an empty string or the value
373 "cat"
374 is equivalent to passing
375 \fB\-\-no\-pager\fR\&.
376 .sp
377 Note: if
378 \fI$SYSTEMD_PAGERSECURE\fR
379 is not set,
380 \fI$SYSTEMD_PAGER\fR
381 and
382 \fI$PAGER\fR
383 can only be used to disable the pager (with
384 "cat"
385 or
386 ""), and are otherwise ignored\&.
387 .RE
388 .PP
389 \fI$SYSTEMD_LESS\fR
390 .RS 4
391 Override the options passed to
392 \fBless\fR
393 (by default
394 "FRSXMK")\&.
395 .sp
396 Users might want to change two options in particular:
397 .PP
398 \fBK\fR
399 .RS 4
400 This option instructs the pager to exit immediately when
401 Ctrl+C
402 is pressed\&. To allow
403 \fBless\fR
404 to handle
405 Ctrl+C
406 itself to switch back to the pager command prompt, unset this option\&.
407 .sp
408 If the value of
409 \fI$SYSTEMD_LESS\fR
410 does not include
411 "K", and the pager that is invoked is
412 \fBless\fR,
413 Ctrl+C
414 will be ignored by the executable, and needs to be handled by the pager\&.
415 .RE
416 .PP
417 \fBX\fR
418 .RS 4
419 This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
420 .RE
421 .sp
422 Note that setting the regular
423 \fI$LESS\fR
424 environment variable has no effect for
425 \fBless\fR
426 invocations by systemd tools\&.
427 .sp
428 See
429 \fBless\fR(1)
430 for more discussion\&.
431 .RE
432 .PP
433 \fI$SYSTEMD_LESSCHARSET\fR
434 .RS 4
435 Override the charset passed to
436 \fBless\fR
437 (by default
438 "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
439 .sp
440 Note that setting the regular
441 \fI$LESSCHARSET\fR
442 environment variable has no effect for
443 \fBless\fR
444 invocations by systemd tools\&.
445 .RE
446 .PP
447 \fI$SYSTEMD_PAGERSECURE\fR
448 .RS 4
449 Common pager commands like
450 \fBless\fR(1), in addition to "paging", i\&.e\&. scrolling through the output, support opening of or writing to other files and running arbitrary shell commands\&. When commands are invoked with elevated privileges, for example under
451 \fBsudo\fR(8)
452 or
453 \fBpkexec\fR(1), the pager becomes a security boundary\&. Care must be taken that only programs with strictly limited functionality are used as pagers, and unintended interactive features like opening or creation of new files or starting of subprocesses are not allowed\&. "Secure mode" for the pager may be enabled as described below,
454 \fIif the pager supports that\fR
455 (most pagers are not written in a way that takes this into consideration)\&. It is recommended to either explicitly enable "secure mode" or to completely disable the pager using
456 \fB\-\-no\-pager\fR
457 or
458 \fIPAGER=cat\fR
459 when allowing untrusted users to execute commands with elevated privileges\&.
460 .sp
461 This option takes a boolean argument\&. When set to true, the "secure mode" of the pager is enabled\&. In "secure mode",
462 \fBLESSSECURE=1\fR
463 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses\&. Currently only
464 \fBless\fR(1)
465 is known to understand this variable and implement "secure mode"\&.
466 .sp
467 When set to false, no limitation is placed on the pager\&. Setting
468 \fISYSTEMD_PAGERSECURE=0\fR
469 or not removing it from the inherited environment may allow the user to invoke arbitrary commands\&.
470 .sp
471 When
472 \fI$SYSTEMD_PAGERSECURE\fR
473 is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it\&. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see
474 \fBgeteuid\fR(2)
475 and
476 \fBsd_pid_get_owner_uid\fR(3), or when running under
477 \fBsudo\fR(8)
478 or similar tools (\fI$SUDO_UID\fR
479 is set
480 \&\s-2\u[1]\d\s+2)\&. In those cases,
481 \fISYSTEMD_PAGERSECURE=1\fR
482 will be set and pagers which are not known to implement "secure mode" will not be used at all\&. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience\&. It is recommended to explicitly set
483 \fI$SYSTEMD_PAGERSECURE\fR
484 or disable the pager\&.
485 .sp
486 Note that if the
487 \fI$SYSTEMD_PAGER\fR
488 or
489 \fI$PAGER\fR
490 variables are to be honoured, other than to disable the pager,
491 \fI$SYSTEMD_PAGERSECURE\fR
492 must be set too\&.
493 .RE
494 .PP
495 \fI$SYSTEMD_COLORS\fR
496 .RS 4
497 Takes a boolean argument\&. When true,
498 \fBsystemd\fR
499 and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
500 "16",
501 "256"
502 to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
503 \fI$TERM\fR
504 and what the console is connected to\&.
505 .RE
506 .PP
507 \fI$SYSTEMD_URLIFY\fR
508 .RS 4
509 The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
510 \fBsystemd\fR
511 makes based on
512 \fI$TERM\fR
513 and other conditions\&.
514 .RE
515 .SH "EXAMPLES"
516 .PP
517 Show current settings:
518 .sp
519 .if n \{\
520 .RS 4
521 .\}
522 .nf
523 $ timedatectl
524 Local time: Thu 2017\-09\-21 16:08:56 CEST
525 Universal time: Thu 2017\-09\-21 14:08:56 UTC
526 RTC time: Thu 2017\-09\-21 14:08:56
527 Time zone: Europe/Warsaw (CEST, +0200)
528 System clock synchronized: yes
529 NTP service: active
530 RTC in local TZ: no
531 .fi
532 .if n \{\
533 .RE
534 .\}
535 .PP
536 Enable network time synchronization:
537 .sp
538 .if n \{\
539 .RS 4
540 .\}
541 .nf
542 $ timedatectl set\-ntp true
543 ==== AUTHENTICATING FOR org\&.freedesktop\&.timedate1\&.set\-ntp ===
544 Authentication is required to control whether network time synchronization shall be enabled\&.
545 Authenticating as: user
546 Password: ********
547 ==== AUTHENTICATION COMPLETE ===
548 .fi
549 .if n \{\
550 .RE
551 .\}
552 .sp
553
554 .sp
555 .if n \{\
556 .RS 4
557 .\}
558 .nf
559 $ systemctl status systemd\-timesyncd\&.service
560 ● systemd\-timesyncd\&.service \- Network Time Synchronization
561 Loaded: loaded (/usr/lib/systemd/system/systemd\-timesyncd\&.service; enabled)
562 Active: active (running) since Mo 2015\-03\-30 14:20:38 CEST; 5s ago
563 Docs: man:systemd\-timesyncd\&.service(8)
564 Main PID: 595 (systemd\-timesyn)
565 Status: "Using Time Server 216\&.239\&.38\&.15:123 (time4\&.google\&.com)\&."
566 CGroup: /system\&.slice/systemd\-timesyncd\&.service
567 └─595 /usr/lib/systemd/systemd\-timesyncd
568 \&...
569 .fi
570 .if n \{\
571 .RE
572 .\}
573 .PP
574 Show current status of
575 \fBsystemd-timesyncd.service\fR(8):
576 .sp
577 .if n \{\
578 .RS 4
579 .\}
580 .nf
581 $ timedatectl timesync\-status
582 Server: 216\&.239\&.38\&.15 (time4\&.google\&.com)
583 Poll interval: 1min 4s (min: 32s; max 34min 8s)
584 Leap: normal
585 Version: 4
586 Stratum: 1
587 Reference: GPS
588 Precision: 1us (\-20)
589 Root distance: 335us (max: 5s)
590 Offset: +316us
591 Delay: 349us
592 Jitter: 0
593 Packet count: 1
594 Frequency: \-8\&.802ppm
595 .fi
596 .if n \{\
597 .RE
598 .\}
599 .sp
600 .SH "SEE ALSO"
601 .PP
602 \fBsystemd\fR(1), \fBhwclock\fR(8), \fBdate\fR(1), \fBlocaltime\fR(5), \fBsystemctl\fR(1), \fBsystemd-timedated.service\fR(8), \fBsystemd-timesyncd.service\fR(8), \fBsystemd-firstboot\fR(1)
603 .SH "NOTES"
604 .IP " 1." 4
605 It is recommended for other tools to set and check
606 \fI$SUDO_UID\fR
607 as appropriate, treating it is a common interface.
608