documentation for new update-motd, supporting running message modules
[update-motd.git] / update-motd.1
1 .IX Title "UPDATE-MOTD 1"
2 .TH UPDATE-MOTD 1 "2008-11-11" update-motd update-motd
3
4 .SH "NAME"
5 update\-motd \- Automatically update the message-of-the-day (MOTD)
6
7 .SH "SYNOPSIS"
8 .IX Header "SYNOPSIS"
9 update\-motd [\-\-disable|\-\-enable|\-\-force] [d|hourly|daily|weekly|monthly]
10
11 .SH "OPTIONS"
12 .IX Header "OPTIONS"
13 .TP
14 \fB\-\-disable\fP
15 Prevent update-motd from running. This is useful for temporarily disabling automatic updates of \fI/etc/motd\fP by the \fI/etc/cron.d/update-motd\fP cronjob.  Note that this regenerates a base MOTD without the update-motd additions, and then exits.
16 .TP
17 \fB\-\-enable\fP
18 Allow update-motd to run.  This is useful for enabling automatic updates of \fI/etc/motd\fP through the \fI/etc/cron.d/update-motd\fP cronjob.  Note that this updates the MOTD immediately.
19 .TP
20 \fB\-\-force\fP
21 Override a disabled update-motd for a single, immediate update of \fI/etc/motd\fP.
22 .TP
23 \fBd\fP (Default)
24 Runs the scripts in /etc/update-motd.d
25 .TP
26 \fBhourly\fP
27 Runs the scripts in /etc/update-motd.d/hourly
28 .TP
29 \fBdaily\fP
30 Runs the scripts in /etc/update-motd.d/daily
31 .TP
32 \fBweekly\fP
33 Runs the scripts in /etc/update-motd.d/weekly
34 .TP
35 \fBmonthly\fP
36 Runs the scripts in /etc/update-motd.d/monthly
37
38
39 .SH "DESCRIPTION"
40 .IX Header "DESCRIPTION"
41 This script executes lists of scripts in lexical order, concatenating and writing the output to \fI/var/lib/motd\fP, which is usually a symbolic link to \fI/etc/motd\fP.
42
43 Users and/or packages should add symbolic links to \fI/etc/update-motd.d/\fP, \fI/etc/update-motd.d/hourly\fP, \fI/etc/update-motd.d/daily\fP, \fI/etc/update-motd.d/weekly\fP, \fI/etc/update-motd.d/monthly\fP, prepended with a two-digit number to define the displayed order, as obeyed by \fBrun-parts(8)\fP.
44
45 Separate cron jobs will run \fBupdate-motd\fP every 10 minutes, hourly, daily, weekly, and monthly.  Each of execution of \fBupdate-motd\fP will run the scripts in the corresponding \fI/etc/update-motd.d/\fP directory.  The output of each script will be written and cached in \fI/var/run/update-motd/*\fP, retaining the number and name of the script executed, to preserve the ordering of the output in \fI/etc/motd\fP.  After execution of the current set of scripts, all files in \fI/var/run/update-motd/\fP will be concatenated with \fI/etc/motd.tail\fP and written to \fI/etc/motd\fP.
46
47 The update-motd script will not execute if the file \fI/var/lib/update-motd/disabled\fP exists.  One can override this using the \fB--force\fP option.  To permanently enable/disable \fBupdate-motd\fP, use:
48     $ sudo update-motd --enable
49     $ sudo update-motd --disable
50
51 If enabled, timestamp of the last \fBupdate-motd\fP run will be written to \fI/var/run/update-motd.lastrun\fP.
52
53 .SH FILES
54 \fI/etc/cron.d/update-motd\fP, \fI/etc/update-motd.d/\fP, \fI/etc/update-motd.d/hourly\fP, \fI/etc/update-motd.d/daily\fP, \fI/etc/update-motd.d/weekly\fP, \fI/etc/update-motd.d/monthly\fP, \fI/etc/motd.tail\fP, \fI/var/run/motd\fP, \fI/var/lib/update-motd/disabled\fP, \fI/var/run/update-motd\fP, \fI/var/run/update-motd.lastrun\fP
55
56 .SH "AUTHOR"
57 .IX Header "AUTHOR"
58 Dustin Kirkland <kirkland@canonical.com>
59
60 .SH "LICENSE"
61 .IX Header "LICENSE"
62 This manpage and the \fBupdate-motd\fP utility  was  written  by Dustin Kirkland <kirkland@canonical.com> for Ubuntu systems (but may be used by others).  Permission is granted to copy, distribute and/or modify  this  document  under the terms of the GNU General Public License, Version 3 or any later version published by the Free  Software  Foundation.
63
64 On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3.