LPI exam 102 prep, Topic 108: Linux documentation

Junior Level Administration (LPIC-1) topic 108

In this tutorial, Ian Shields continues preparing you to take the Linux Professional Institute® Junior Level Administration (LPIC-1) Exam 102. In this fourth in a series of nine tutorials, Ian introduces you to Linux® documentation. By the end of this tutorial, you will know how to use and manage local documentation, find documentation on the Internet, and use automated logon messages to notify users of system events.

Share:

Ian Shields, Senior Programmer, IBM developerWorks

Ian ShieldsIan Shields works on a multitude of Linux projects for the developerWorks Linux zone. He is a Senior Programmer at IBM at the Research Triangle Park, NC. He joined IBM in Canberra, Australia, as a Systems Engineer in 1973, and has since worked on communications systems and pervasive computing in Montreal, Canada, and RTP, NC. He has several patents and has published several papers. His undergraduate degree is in pure mathematics and philosophy from the Australian National University. He has an M.S. and Ph.D. in computer science from North Carolina State University. Learn more about Ian in Ian's profile on developerWorks Community.



20 September 2006

Before you start

Learn what these tutorials can teach you and how you can get the most from them.

About this series

The Linux Professional Institute (LPI) certifies Linux system administrators at two levels: junior level (also called "certification level 1") and intermediate level (also called "certification level 2"). To attain certification level 1, you must pass exams 101 and 102; to attain certification level 2, you must pass exams 201 and 202.

developerWorks offers tutorials to help you prepare for each of the four exams. Each exam covers several topics, and each topic has a corresponding self-study tutorial on developerWorks. For LPI exam 102, the nine topics and corresponding developerWorks tutorials are:

Table 1. LPI exam 102: Tutorials and topics
LPI exam 102 topicdeveloperWorks tutorialTutorial summary
Topic 105LPI exam 102 prep:
Kernel
Learn how to install and maintain Linux kernels and kernel modules.
Topic 106LPI exam 102 prep:
Boot, initialization, shutdown, and runlevels
Learn how to boot a system, set kernel parameters, and shut down or reboot a system.
Topic 107LPI exam 102 prep:
Printing
Learn how to manage printers, print queues and user print jobs on a Linux system.
Topic 108 LPI exam 102 prep:
Documentation
(This tutorial). Learn how to use and manage local documentation, find documentation on the Internet, and use automated logon messages to notify users of system events. See detailed objectives below.
Topic 109 LPI exam 102 prep:
Shells, scripting, programming and compiling
Coming soon.
Topic 111 LPI exam 102 prep:
Administrative tasks
Coming soon.
Topic 112 LPI exam 102 prep:
Networking fundamentals
Coming soon.
Topic 113 LPI exam 102 prep:
Networking services
Coming soon.
Topic 114 LPI exam 102 prep:
Security
Coming soon.

To pass exams 101 and 102 (and attain certification level 1), you should be able to:

  • Work at the Linux command line
  • Perform easy maintenance tasks: help out users, add users to a larger system, back up and restore, and shut down and reboot
  • Install and configure a workstation (including X) and connect it to a LAN, or connect a stand-alone PC via modem to the Internet

To continue preparing for certification level 1, see the developerWorks tutorials for LPI exams 101 and 102, as well as the entire set of developerWorks LPI tutorials.

The Linux Professional Institute does not endorse any third-party exam preparation material or techniques in particular. For details, please contact info@lpi.org.

About this tutorial

Welcome to "Linux documentation," the fourth of nine tutorials designed to prepare you for LPI exam 102. In this tutorial, you learn how to use and manage local documentation, find documentation on the Internet, and use automated logon messages to notify users of system events.

This tutorial is organized according to the LPI objectives for this topic. Very roughly, expect more questions on the exam for objectives with higher weight.

Table 2. Documentation: Exam objectives covered in this tutorial
LPI exam objectiveObjective weightObjective summary
1.108.1
Use and manage local system documentation
Weight 4Find relevant man pages and search man page sections. Find commands and the man pages related to them. Configure access to man sources and the man system. Prepare man pages for printouts. Use the system documentation stored in /usr/share/doc/ and determine what documentation to keep in /usr/share/doc/.
1.108.2
Find Linux documentation on the Internet
Weight 3Use Linux documentation at sources such as the Linux Documentation Project (LDP), vendor and third-party Web sites, newsgroups, newsgroup archives, and mailing lists.
1.108.5
Notify users of system-related issues
Weight 1Notify the users about current issues related to the system through logon messages.

Prerequisites

To get the most from this tutorial, you should have a basic knowledge of Linux and a working Linux system on which to practice the commands covered in this tutorial. You will also need a connection to the Internet.

This tutorial builds on content covered in previous tutorials in this LPI series, so you may want to first review the tutorials for exam 101.

Different versions of a program may format output differently, so your results may not look exactly like the listings and figures in this tutorial.


Local documentation

This section covers material for topic 1.108.1 for the Junior Level Administration (LPIC-1) exam 102. The topic has a weight of 4.

In this section, learn how to:

  • Find relevant man pages
  • Search man page sections
  • Find commands and man pages related to them
  • Configure access to man sources and the man system
  • Prepare man pages for printouts
  • Use the system documentation stored in /usr/share/doc/ and determine what documentation to keep in /usr/share/doc/

Find man pages

The primary (and traditional) source of documentation is the manual pages, which you can access using the man command. Ideally, you can look up the man page for any command, configuration file, or library routine. In practice, Linux is free software, and some pages haven't been written or are showing their age. Nonetheless, man pages are the first place to look when you need help. Figure 1 illustrates the manual page for the man command itself. Use the command man man to display this information.

Figure 1. Man page for the man command
Man page for man command

Figure 1 shows some typical items in man pages:

  1. A heading with the name of the command followed by its section number in parentheses
  2. The name of the command and any related commands that are described on the same man page
  3. A synopsis of the options and parameters applicable to the command
  4. A short description of the command
  5. Detailed information on each of the options

You may find other sections on usage, how to report bugs, author information, and a list of any related commands. For example, the man page for man tells us that related commands (and their manual sections) are:

apropos(1), whatis(1), less(1), groff(1), and man.conf(5).

Man pages are displayed using a pager, which is usually the less command on Linux systems. You can set this using the $PAGER environment variable, or by using the -P or --pager option, along with another pager name, on the man command. The pager will receive its input on stdin, so something like an editor that expects a file to manipulate does not work as a pager.

There are eight common manual page sections. Manual pages are usually installed when you install a package, so if you do not have a package installed, you probably won't have a manual page for it. Similarly, some of your manual sections may be empty or nearly empty. The common manual sections, with some example contents are:

  1. User commands (env, ls, echo, mkdir, tty)
  2. System calls or kernel functions (link, sethostname, mkdir)
  3. Library routines (acosh, asctime, btree, locale, XML::Parser)
  4. Device-related information (isdn_audio, mouse, tty, zero)
  5. File format descriptions (keymaps, motd, wvdial.conf)
  6. Games (note that many games are now graphical and have graphical help outside the man page system)
  7. Miscellaneous (arp, boot, regex, unix utf8)
  8. System administration (debugfs, fdisk, fsck, mount, renice, rpm)

Other man page sections that you might find include 9 for Linux kernel documentation, n for new documentation, o for old documentation, and l for local documentation.

Some entries appear in multiple sections. Our examples show mkdir in sections 1 and 2, and tty in sections 1 and 4.

The info command

In addition to the standard manual pages, the Free Software Foundation has created a number of info files that are processed with the info program. These provide extensive navigation facilities including the ability to jump to other sections. Try man info or info info for more information. Not all commands are documented with info, so you will find yourself using both man and info if you become an info user. You can also start at the top of the info tree by using info without parameters as shown in Listing 1.

Listing 1. The info command
File: dir,      Node: Top       This is the top of the INFO tree

  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "?" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.

  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.

* Menu:

Utilities
* Bash: (bash).                     The GNU Bourne-Again SHell.
* Enscript: (enscript).             GNU Enscript
* Gzip: (gzip).                 The gzip command for compressing files.
* ZSH: (zsh).                     The Z Shell Manual.

Libraries
* AA-lib: (aalib).              An ASCII-art graphics library
* History: (history).       The GNU history library API
* Libxmi: (libxmi).           The GNU libxmi 2-D rasterization library.
* Readline: (readline).       The GNU readline library API


Texinfo documentation system
* Info: (info).                 Documentation browsing system.
-----Info: (dir)Top, 2104 lines --Top-------------------------------------------
Welcome to Info version 4.6. Type ? for help, m for menu item.

Graphical man page interfaces

In addition to the standard man command, which uses a terminal window and a pager, your system may also have one or more graphical interfaces to manual pages, such as xman (from the XFree86 Project) and yelp (the Gnome help browser).

When you start xman, you will see a small window with three buttons. Click the Manual Page button to open a larger window where you can navigate through manual pages or search for information. Figure 2 shows an example of both windows.

Figure 2. Using xman
Using xman

The yelp browser usually looks somewhat different from system to system. Figure 3 shows an example on Ubuntu 6.06. You can access either the man pages or the info pages using the Command Line Help item at the bottom of the display.

Figure 3. Using yelp on Ubuntu
Using yelp on Ubuntu

Search man pages

If you know that a topic occurs in a particular section, you can specify the section. For example, man 4 tty or man 2 mkdir. An alternative is to use the -a option to display all applicable manual sections. If you specify -a, you will be prompted after quitting the page for each section. You may skip the next page, view it, or quit altogether.

As you saw earlier, some topics exist in more than one section. If you don't want to search through each section, you can use the -aw options of man to get a list of all available man pages for a topic. Listing 2 shows an example for printf. If you were writing a portable shell script, you might be interested in man 1p printf to learn about the POSIX version of the printf command. On the other hand, if you were writing a C or C++ program, you would be more interested in man 3 printf, which would show you the documentation for the printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, and vsnprintf library functions.

Listing 2. Available man pages for printf
ian@lyrebird:~> man -aw printf
/usr/share/man/man1/printf.1.gz
/usr/share/man/man1p/printf.1p.gz
/usr/share/man/man3/printf.3.gz

The man command pages output onto your display using a paging program. On most Linux systems, this is likely to be the less program. Another choice might be the older more program.

The less pager has several commands that help you search for strings within the displayed output. These are similar to vi editing commands. Use man less to find out more about / (search forwards), ? (search backwards), and n (repeat last search), among many other commands.

The info command comes from the makers of emacs, so the searching commands are more like emacs commands. For example, ctrl-s searches forwards and ctrl-r searches backwards using an incremental search. You can also move around with the arrow keys, follow links (indicated with a star) using the Enter key, and quit using q. Use the --vi-keys option with info if you'd prefer similar key bindings to those used for man.

Find commands

Two important commands related to man are whatis and apropos. The whatis command searches man pages for the name you give and displays the name information from the appropriate manual pages. The apropos command does a keyword search of manual pages and lists ones containing your keyword. Listing 3 illustrates these commands.

Listing 3. Whatis and apropos examples
[ian@lyrebird ian]$ whatis man
man                  (1)  - format and display the on-line manual pages
man                  (7)  - macros to format man pages
man [manpath]        (1)  - format and display the on-line manual pages
man.conf [man]       (5)  - configuration data for man
[ian@lyrebird ian]$ whatis mkdir
mkdir                (1)  - make directories
mkdir                (2)  - create a directory
[ian@lyrebird ian]$ apropos mkdir
mkdir                (1)  - make directories
mkdir                (2)  - create a directory
mkdirhier            (1x)  - makes a directory hierarchy

By the way, if you cannot find the manual page for man.conf, try running man man.config instead, which works on some systems.

The apropos command can produce a lot of output, so you may need to use more complex regular expressions rather than simple keywords. Alternatively, you may wish to filter the output through grep or another filter to reduce the output to something more of interest. As a practical example, you can use the e2label to display or change the label on an ext2 or ext3 filesystem, but you have to use another command to change the label on a ReiserFS filesystem. Suppose you run mount to display the mounted ResiserFS filesystems as shown in Listing 4.

Listing 4. Mounted ReiserFS filesystems
ian@lyrebird:~> mount -t reiserfs
LABEL=SLES9 on / type reiserfs (rw,acl,user_xattr)

Now you'd like to know what partition corresponds to the label SLES9, but you can't remember the command. Using apropos label might get you a couple of dozen responses, which isn't too bad to sift through. But wait. This command must have something to do with a filesystem of a volume. So you try the regular expressions shown in Listing 5.

Listing 5. Using apropos with regular expressions
ian@lyrebird:~> apropos "label.*file"
e2label (8)          - Change the label on an ext2/ext3 filesystem
ntfslabel (8)        - display/change the label on an ntfs file system
ian@lyrebird:~> apropos "label.*volume"
label.*volume: nothing appropriate.

Not exactly what you were looking for. You could try reversing the order of the terms in the regular expressions, or you could try filtering through grep or egrep as shown in Listing 6.

Listing 6. Filtering the output of apropos
ian@lyrebird:~> apropos label | grep -E "file|volume"
e2label (8)          - Change the label on an ext2/ext3 filesystem
mlabel (1)           - make an MSDOS volume label
ntfslabel (8)        - display/change the label on an ntfs file system
findfs (8)           - Find a filesystem by label or UUID

And there's the command that we need, findfs. Using it as shown in Listing 7 shows that the filesystem is on /dev/hda10 on this particular system.

Listing 7. Finding the device for a mounted filesystem label
ian@lyrebird:~> /sbin/findfs LABEL=SLES9
/dev/hda10

Note that non-root users will usually have to give the full path to the findfs command.

As you can find out in the man page for the man command, you can also use man -k instead of apropos and man -f instead of whatis. Since these call the apropos or whatis command under the covers, there is probably little point in so doing.

Configuration

Manual pages may be in many locations on your system. You can determine the current search path using the manpath command. If the MANPATH environment variable is set, this will be used for searching for manual pages; otherwise, a path will be built automatically using information from a configuration file that we'll discuss in a moment. If the MANPATH environment variable is set, the manpath command will issue a warning message to this effect before displaying the path.

Listing 8. Displaying your MANPATH
[ian@echidna ian]$ manpath
/usr/local/share/man:/usr/share/man:/usr/X11R6/man:/usr/local/man

ian@lyrebird:~> manpath
manpath: warning: $MANPATH set, ignoring /etc/manpath.config
/usr/local/man:/usr/share/man:/usr/X11R6/man:/opt/gnome/share/man

Depending on your system, configuration information for the man system is stored in /etc/man.config or /etc/manpath.confg. Older systems use /etc/man.conf. A current man.config file contains a list of directories (MANPATHs) that will be searched for manual pages, such as those shown in Listing 9.

Listing 9. MANPATH entries from /etc/man.config
MANPATH /usr/share/man
MANPATH /usr/man
MANPATH /usr/local/share/man
MANPATH /usr/local/man
MANPATH /usr/X11R6/man

In a manpath.config file, these entries will be MANDATORY_MANPATH entries, rather than MANPATH entries.

Besides these entries, you will also find entries giving a mapping between paths where executables may be found, and paths where the corresponding man pages might be, as shown in Listing 10.

Listing 10. MANPATH_MAP entries from /etc/man.config
MANPATH_MAP     /bin                    /usr/share/man
MANPATH_MAP     /sbin                   /usr/share/man
MANPATH_MAP     /usr/bin                /usr/share/man
MANPATH_MAP     /usr/sbin               /usr/share/man
MANPATH_MAP     /usr/local/bin          /usr/local/share/man

The man command uses a complicated method for searching for man pages, and setting these values will result in less wasted effort when searching for pages.

Another entry in the configuration file defines the search order for manual pages. Recall that the default is to display the first page found, so this ordering is important. Look near the bottom of man.config for a MANSECT line, or near the bottom of manpath.config for a SECTION line. Examine the configuration file on your system to see what other things can be configured.

You may have noticed that the apropos and whatis commands ran quickly. This is because they do not actually search the individual manual pages. Rather, they use a database created by the makewhatis command. This is usually run by the system either daily or weekly as a cron job.

Listing 11. Running makewhatis
[root@echidna root]# makewhatis

The command completes normally without any output message, but the whatis database is refreshed. This is usually stored in a location such as /var/cache/man/whatis. Note that some SUSE systems do not use the whatis database and therefore do not have a makewhatis command.

Printing man pages

If you wish to print the page, specify the -t option to format the page for printing using the groff or troff program. This will format the page for the default printer and send the output to stdout. Listing 12 shows how to format the man page for the ls command and save the output in a file, ls.ps. Figure 4 shows the formatted output.

Listing 12. Formatting the ls manpage for printing
ian@pinguino:~$ man -t ls > ls.ps
Figure 4. Formatted ls man page
Formatted ls man page

If you need to format the page for a different device type, use the -T options with a device type, such as dvi or ps. See the man page for man for additional information.

/usr/share/doc/

In addition to the manual pages and info pages that you have already seen, your Linux system probably includes a lot more documentation. The customary place to store this is in /usr/share/doc, or /usr/doc on older systems. This additional documentation may be in any of several formats, such as text, PDF, PostScript, or HTML.

Searching through this documentation can often reveal gems that aren't available as man pages or info pages, such as tutorials or additional technical documentation. As Listing 13 shows, there can be a large number of files in /usr/share/doc, so you have plenty of reading resources.

Listing 13. Files in /usr/share/doc
ian@pinguino:~$ find /usr/share/doc -type f | wc -l
10144

Figure 5 shows an example of the HTML help for the Texinfo system that is used for the info command that you saw earlier.

Figure 5. Texinfo HTML help from /usr/share/doc
Texinfo HTML help from /usr/share/doc

Sometimes, a man page will direct you to another source for documentation. For example, the man page for the pngtopnm command is shown in Listing 14. It directs you to a local copy in HTML format at /usr/share/doc/packages/netpbm/doc/pngtopnm.html, or to an online version if you do not have the local copy.

Listing 14. Pointer man page for pngtopnm
pngtopnm(1)          Netpbm pointer man pages         pngtopnm(1)



pngtopnm  is part of the Netpbm package.  Netpbm documentation is
kept in HTML format.

Please refer to
 <http://netpbm.sourceforge.net/doc//pngtopnm.html>.

If that doesn't work,  also  try  <http://netpbm.sourceforge.net>
and emailing Bryan Henderson, bryanh@giraffe-data.com.

Local copy of the page is here:
 /usr/share/doc/packages/netpbm/doc/pngtopnm.html

Other command help

Finally, if you can't find help for a command, try running the command with the --help, --h, or --? option. This may provide the command's help, or it may tell you how to get the help you need. Listing 15 shows an example for the kdesu command, which is usually present on systems with a KDE desktop.

Listing 15. Getting help for kdesu command
ian@lyrebird:~> man kdesu
No manual entry for kdesu
ian@lyrebird:~> kdesu --help
Usage: kdesu [Qt-options] [KDE-options] command

Runs a program with elevated privileges.

Generic options:
  --help                    Show help about options
  --help-qt                 Show Qt specific options
  --help-kde                Show KDE specific options
  --help-all                Show all options
  --author                  Show author information
  -v, --version             Show version information
  --license                 Show license information
  --                        End of options

Arguments:
  command                   Specifies the command to run.

Options:
  -c <command>              Specifies the command to run. []

The next section covers online resources for help with Linux.


Internet documentation

This section covers material for topic 1.108.2 for the Junior Level Administration (LPIC-1) exam 102. The topic has a weight of 3.

In this section, learn how to find:

  • Online documentation
  • Newsgroups
  • Mailing lists

Online documentation

In addition to the documentaiton on your system, there are many online sources of documentation and help.

The Linux Documentation Project

The Linux Documentation Project is volunteer effort that is putting together the complete set of free Linux documentation. This project exists to consolidate various pieces of Linux documentation into a location that is easy to search and use.

The LDP is made up of the following areas:

HOWTOs
are subject-specific help, such as the Linux IPv6 HOWTO.
Guides
are longer, in-depth books, such as Introduction to Linux - A Hands on Guide.
FAQs
are Frequently Asked Questions, such as the Linux Documentation Project (LDP) FAQ.
man pages
are help on individual commands, as you used in the previous section of this tutorial.
Linux Gazette
is an online magazine, currently available in English, French, German, Indonesian, Italian, Portuguese, Russian, and Spanish.

The examples here take you to the multiple-page HTML versions of the documentation. You will find most articles come in several formats, including single-page HTML, PDF, or plain text, among others.

The LDP also has links to information in languages other than English.

The LDP site is well laid out with excellent navigation. If you aren't sure which section to peruse, you can take advantage of the search box, which helps you find things by topic.

If you'd like to help the LDP with Linux documentation, be sure to consult the LDP Author Guide.

Distributor Web sites

Web sites for the various Linux distributions often provide updated documentation, installation instructions, hardware compatibility/incompatibility statements, and other support such as a knowledge base search tool. Some of these are:

  • Redhat Linux is a large distributor of enterprise Linux products based in the United States.
  • SUSE Linux was founded in Germany and is now owned by Novell.
  • Asianux is an Asian Linux distributor, founded by Haansoft,Inc., Red Flag Software Co., Ltd., and Miracle Linux Corporation.
  • Turbolinux is headquartered in Japan but distributes outside Asia as well.
  • Yellow Dog Linux from Terra Soft Solutions is a distribution for Apple PowerPC®-based processors, and embedded processors based on PowerPC and Cell processors.
  • Linspire is a desktop version of Linux that can be found on some preloaded systems.
  • The Slackware Linux Project by Patrick Volkerding has been around since 1993 and aims to be the most "UNIX®-like" Linux distribution out there.
  • Debian GNU/Linux was started in 1993 as a distribution that was created openly, in the spirit of Linux and GNU.
  • Ubuntu Linux is a relatively new distribution of Linux based on Debian. It focuses on ease-of-use and has related projects, Kubuntu (a version using the KDE desktop), Edubuntu (designed for school environments), and Xubuntu (a lightweight version using the Xfce desktop environment).
  • Gentoo Linux is a distribution that can be automatically optimized and customized for just about any application or need. Packages are distributed as source and built to suit the target environment.
  • Mandriva is a distribution featuring ease-of-use. The company was formed from the merger of several open source pioneers such as Mandrakesoft in France, Conectiva in Brazil, Edge IT in France, and Lycoris in the US.

You can find summary information on and links to a large number of Linux distributions at DistroWatch.com. Tabular information on each distribution tells you what levels of which major packages are included in each version, when the version was released, and much other useful information.

Hardware and software vendors

Many hardware and software vendors have added Linux support to their products in recent years. At their sites, you can find information about which hardware supports Linux, software development tools, released sources, downloads of Linux drivers for specific hardware, and other special Linux projects. For example:

Open source projects

Many open source projects have home pages where you will find information on the project. Some projects are sponsored by a foundation such as the Apache Software Foundation. Some examples are:

A large number of open source projects are hosted on SourceForge.net. These are grouped into categories such as clustering, database, desktop, financial, multimedia, security, and so on. Project pages include links for downloading, bug reporting, user forums, and a link to a project's home page (if available) where you will usually find more information about the project.

Other resources

Another great place for Linux information is the IBM developerWorks Linux zone, the home of this tutorial as well as many other fine articles and tutorials for Linux developers.

Many print magazines also have online sites, and some news sites exist only on the Web. Some examples are:

Newsgroups

Internet newsgroups are, more accurately, a form of discussion lists. They grew out of bulletin boards, which were an early means of sharing information, usually over a dial-up link. Newsgroups use a protocol called Network News Transfer Protocol (NNTP), which is defined in IETF RFC 997 (February 1986).

To participate, you use a news reader, which is also known as an NNTP client. There are many Linux clients including evolution, gnus, pan, slrn, thunderbird, and tin. Some of these use a text-mode interface, and some are graphical. The main advantage of a newsgroup is that you take part in the discussion only when you want to, instead of having it continually arrive in your in-box.

Usenet is the largest source of newsgroups. There are several major categories, such as comp for computing, sci for scientific subjects, and rec for recreational topics such as hobbies and games. Computing is further categorized into subjects, and these are still further categorized, so the newsgroups of primary interest to Linux users start with comp.os.linux. You can browse a list on the LDP site.

Your Internet Service Provider probably mirrors a range of newsgroups, although news articles may not be retained for a very long period, particularly for active newsgroups. Several newsgroup providers offer a paid service that may provide longer retention, faster access, or a wider selection of newsgroups.

Figure 6 shows the comp.os.linux tree as carried on one ISP, using Mozilla's Thunderbird as a newsreader. You subscribe to newsgroups, and your newsreader displays only the subscribed groups. Subscribed groups are shown here with a checkmark.

Figure 6. Subscribing to comp.os.linux.* newsgroups
Subscribing to comp.os.linux.* newsgroups

Newsgroup discussions are often archived. A popular newsgroup for many years was Deja News. When it finally ceased, the newsgroup archives were acquired by Google and reintroduced as Google Groups.

More recently, various Web-based forums have arisen. These typically function in a way quite similar to newsgroups, but require only a browser and no configuration. An example is the Linux tech support forum on IBM's developerWorks Web site where you can ask questions about this series of tutorials along with other topics.

Mailing lists

Mailing lists provide probably the most important point of collaboration for Linux developers. Often projects are developed by contributors who live far apart, possibly even on opposite sides of the globe. Mailing lists overcome time zone differences and thus provide a method for each developer on a project to contact all the others, and to hold group discussions via e-mail. One of the most famous development mailing lists is the Linux Kernel Mailing List.

Mailing lists allow members to send a message to the list, and the list server then broadcasts the message to all members of the group. Individual members do not need to know the e-mail addresses of every member of the group, and they do not need to maintain lists of current members. To avoid a flood of messages from busy lists, most lists allow a user to request a daily digest or single message containing all the list postings for the day.

In addition to development, mailing lists can provide a method for asking questions and receiving answers from knowledgeable developers, or even other users. For example, individual distributions often provide mailing lists for newcomers. You can check your distribution's Web site for information on the mailing lists it provides.

If you took the time to read the LKML FAQ at the link above, you might have noticed that mailing list subscribers often don't take kindly to questions being asked repeatedly. It's always wise to search the archives for a given mailing list before writing your question. Chances are, it will save you time, too. And, speaking of archives, these are often mirrored in multiple sites, so use the closest mirror, typically one in your country or continent.


Notifying users

This section covers material for topic 1.108.5 for the Junior Level Administration (LPIC-1) exam 102. The topic has a weight of 1.

In this section, learn how to:

  • Notify the users about current issues related to the system through logon messages

Logon messages

The final short section of this tutorial introduces you to three different logon messages. These have their roots in non-graphical ASCII terminal access to multiuser UNIX® systems and are of diminishing importance today when many workstations are single-user systems, and much access uses a graphical workstation running a desktop such as GNOME or KDE, where these facilities are all but inoperative.

/etc/issue and /etc/issue.net

The first two of these, /etc/issue and /etc/issue.net, are displayed on an ASCII terminal that is connected locally (/etc/issue) or remotely (/etc/issue.net). Listing 16 illustrates these two files as found on a stock Fedora Core 5 system.

Listing 16. /etc/issue and /etc/issue.net
[ian@attic4 ~]$ cat /etc/issue
Fedora Core release 5 (Bordeaux)
Kernel \r on an \m

[ian@attic4 ~]$ cat /etc/issue.net
Fedora Core release 5 (Bordeaux)
Kernel \r on an \m
[ian@attic4 ~]$

Notice the control sequences \r and \m. These allow information such as date or system name to be inserted in the message. The control sequences are shown in Table 4 and are the same as allowed for the mingetty command.

Table 4. Control sequences for /etc/issue and /etc/issue.net
SequencePurpose
\dInserts the current day according to localtime
\lInserts the line on which mingetty is running
\mInserts the machine architecture (equivalent to uname -m)
\nInserts the machine's network node hostname (equivalent to uname -n)
\oInserts the domain name
\rInserts the operating system release (equivalent to uname -r)
\t Inserts the current time according to localtime
\sInserts the operating system name
\u or \UInserts the current number of users logged in. \U inserts "n users", while \u inserts only "n".
\vInserts the operating system version (equivalent to uname -v)

So you can see that the examples in Listing 16 insert the operating system release level and the machine architecture. Connecting via telnet to this system will cause the /etc/issue.net message to be displayed before the login prompt as shown in Listing 17.

Listing 17. Telnet connections display /etc/issue.net
Fedora Core release 5 (Bordeaux)
Kernel 2.6.17-1.2174_FC5 on an x86_64
login: ian
Password:

If you update /etc/issue.net to include a few more control sequences as shown in Listing 18, your logon prompt might look like that in Listing 19.

Listing 18. Updated /etc/issue.net
[ian@attic4 ~]$ cat /etc/issue.net
Fedora Core release 5 (Bordeaux)
Kernel \r on an \m

\n
Date \d
Time \t
Listing 19. Revised telnet logon prompt
Fedora Core release 5 (Bordeaux)
Kernel 2.6.17-1.2174_FC5 on an x86_64
localhost.localdomain
Date 22:55 on Friday, 15 September 2006
Time 22:55 on Friday, 15 September 2006



login: ian
Password:

Notice that on this system \d and \t produce the same result. As it happens, neither \u nor \U insert the number of users logged in. This perhaps reflects the fact that these messages have very little use these days. The use of telnet with its passwords flowing in the clear is strongly discouraged. Since a connection using ssh passes the login id and therefore bypasses a login prompt, and since real ASCII terminals remotely connected are rare, the contents of /etc/issue.net are rarely seen, and probably not tested too well either.

You will see the contents of /etc/issue if you do not use a graphical login. Even if you do, you can usually get a non-graphical login at the system console using Ctrl-Alt-F1 through Ctrl-Alt-F6, with Ctrl-Alt-F7 returning you to the graphical terminal.

Message of the day

Both /etc/issue and /etc/issue.net provide user feedback in the form of a logon prompt and could also be used to advise users of issues such as impending outages. However, this is usually done with a message of the day or motd, which is stored in /etc/motd. The contents of /etc/motd are displayed after a successful login but just before the login shell is started. Listing 20 shows an example of a motd file, and Listing 21 shows how it and /etc/issue.net appear to a user logging in through a telnet session.

Listing 20. Sample message of the day (motd)
[ian@attic4 ~]$ cat /etc/motd

PLEASE NOTE!

All systems will shut down this weekend for emergency power testing.

Save your work or lose it.
Listing 20. Sample message of the day (motd)
Fedora Core release 5 (Bordeaux)
Kernel 2.6.17-1.2174_FC5 on an x86_64
localhost.localdomain
Date 22:55 on Friday, 15 September 2006
Time 22:55 on Friday, 15 September 2006



login: ian
Password:
Last login: Fri Sep 15 22:54:18 from 192.168.0.101

PLEASE NOTE!

All systems will shut down this weekend for emergency power testing.

Save your work or lose it.
[ian@attic4 ~]$

Again, the motd is really only useful on ASCII terminal sessions. Neither KDE nor GNOME desktops have an easy and satisfactory way of displaying it.

One final notification method that you should know about is the wall command, which sends a warning to all logged-in users using text from either a file or stdin. Again, these are not seen by users using the standard GNOME or KDE desktops.

Don't forget to rate this tutorial and give us your feedback.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Linux on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Linux, Open source
ArticleID=161154
ArticleTitle=LPI exam 102 prep, Topic 108: Linux documentation
publish-date=09202006