7    Documentation Notes

This chapter contains release notes that apply to DIGITAL UNIX Version 4.0D documentation. It discusses the following topics:

• Documentation Overview

• Network Administration

• System Administration

• Assembly Language Programmer's Guide

• Programming with ONC RPC

• Developing Applications for the Display PostScript System

• Gate Daemon Configuration Guide

• Online help volumes

7.1    Documentation Overview

The online version of the Documentation Overview, Glossary, and Master Index has been changed in the following ways for this release:

• It has been divided into two separate books: Documentation Overview and Glossary and Master Index.

• Information in the Documentation Overview has been reorganized and expanded to provide a more comprehensive view of the DIGITAL UNIX documentation set and other information of importance to users of the DIGITAL UNIX operating system.

Because only the online version has changed, that version differs substantially from the printed version.

Also, the Master Index was not revised for this release; therefore, some of the index entries for books that have been revised since the Version 4.0 release may be inaccurate.

A new printed version of the Documentation Overview will be offered with the next major release of DIGITAL UNIX. At that time, the Glossary and Master Index will also be updated and provided as a separate book in both online and printed versions.

7.2    Network Administration Guide

The following sections describe changes to the Network Administration manual.

7.2.1    Section 4.2.2.2 (Verifying PPP Support in the Kernel) Is Obsolete

The following instructions replace the instructions in Section 4.2.2.2:

To verify that PPP is supported in the kernel, enter the following command:

#  sysconfig -s | grep ppp

If it is not loaded and configured, do the following:

1. Log in as root.

2. Save the /vmunix file.

3. Rebuild the kernel by running the doconfig program and selecting the Point-to-Point Protocol (PPP) option.

4. Copy the new vmunix file to /vmunix.

5. Add the following entry to the /etc/sysconfigtab file using the sysconfigdb utility:

   ppp:
   nppp=2
   

   This provides for 2 PPP connections. If your system requires a greater number of PPP connections, increase the number.

6. Reboot the system.

7.2.2    Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3 Are Obsolete

The following instructions replace the instructions in Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3:

7.2.2.1    Establishing a PPP Dial-Out Connection

After you have connected your modem to a serial port on your system, or installed a supported modem card option, do the following:

1. Verify that you can communicate with the modem. Do the following:

   1. Edit the /etc/remote file and copy the kdebug entry.

   2. Modify the new entry, providing a system name for the entry, the correct DIGITAL UNIX device (tty00 or tty01 depending on your system), the correct baud rate, and correct parity. See the remote(4) reference page for more information.

   3. Use the tip command to access the modem as follows:

      %  tip system_name
      

      system_name is the system name from the /etc/remote file.

   4. If your modem is using the AT command language, enter the following command:

      AT[Return]
      

      If the modem is not in quiet mode, it responds with an OK message.

2. Contact the remote system administrator or your internet service provider (ISP) and obtain the following information:

   • Your remote IP address and netmask, unless the remote system assigns the IP address dynamically

   • Characters that might need to be escaped

   • Instructions on how to log in and use the remote service

   This information is used to create a chat script, which automates the dial-out process.

3. Create a file for commands that the chat program uses to direct the modem what number to dial and what to send the remote system in order to start pppd. This file is called a chat script. Each entry in a chat script has the following format:

   string_chat_expects string_chat_sends

   For example, the following file, named /etc/ppp/chat-script, contains the following information:

    atdt2135476    [1]
   CONNECT     [2]
   login: myname      [3]
   Password: "\qmypassword"    [4]
   "$ " "\qpppd"       [5]
   

   1. The chat script expects nothing and sends a dial command to the modem. [Return to example]

   2. The chat script expects a CONNECT message and sends a carriage return (implied). [Return to example]

   3. The chat script expects the login: string and sends the myname string. [Return to example]

   4. The chat script expects the Password: string and sends the mypassword string. The /eq escape sequence prevents chat from logging the password when you use the -v option. [Return to example]

   5. The chat script expects the $ (the shell prompt) and sends pppd to start the pppd daemon on the remote machine. The \q escape sequence cancels the effect of the previous \q. [Return to example]

   See the chat(8) reference page for more information on chat and chat scripts.

   Note

   You might want to use the tip command to dial out and log in to the remote system and to write down the exact prompt, login sequence, and pppd start-up sequence.

4. Edit the /etc/ppp/options file and include the following pppd options as required by the remote system or ISP:

   defaultroute   [1]
   asyncmap 0  [2]
   mru 296 [3]
   netmask dd.dd.dd.dd  [4]
   lcp-echo-interval 60  [5]
   lcp-echo-failure 5   [6]
   noipdefault  [7]
   crtscts  [8]
   debug  [9]
   

   1. If your system is a standalone and you are connecting to the Internet through the remote system, add a default route via the remote host by specifying this option. [Return to example]

   2. If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example]

   3. Reduces the maximum receive unit (MRU) on the local and remote systems to improve performance for multiple IP connections. [Return to example]

   4. Sets the interface netmask to the specified value. Your ISP should provide this information. [Return to example]

   5. Sends a Link Control Protocol (LCP) echo request frame to the remote system every 60 seconds. This determines whether the link to the remote system is still active. [Return to example]

   6. If the local system does not receive a response from the remote system after five LCP echo request frames, pppd considers the link dead and tears down the connection. [Return to example]

   7. Specifies that the remote system (ISP) is to provide an IP address to the local system, unless an IP address is specified explicitly on the command line or in an options file. [Return to example]

   8. Enables hardware flow control on the serial device. If the modem does not support hardware flow control, do not add this entry. See your modem documentation to verify this information. [Return to example]

   9. Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file. [Return to example]

   See the pppd(8) reference page for a complete list of pppd options.

5. Edit the /etc/syslog.conf file and do the following:

   1. Add the local2 facility (used by pppd and chat) to the line that specifies /dev/console as the message destination, as follows:

      kern.debug;local2.notice      /dev/console
      

      In this example, the notice level is specified.

   2. Add the following entry to the file to create a ppp-log file:

      local2.debug       /etc/ppp/ppp-log
      

   3. Save the edits and close the file.

6. Stop and restart syslogd by entering the following commands:

   #  /sbin/init.d/syslog stop
#  /sbin/init.d/syslog start
   

7. Invoke pppd on the local system to connect to the remote system. For example, the following command starts a link on tty01 and specifies the connect option to run the chat program and the specified chat script file.

   %  pppd /dev/tty01 38400 connect 'chat -v -f /etc/ppp/chat-script'
   

8. Issue the following command to monitor the ppp-log file and to determine whether the PPP connection is active:

   %  tail -f /etc/ppp/ppp-log
   

If any problems occur while using PPP, see Chapter 13 in Network Administration.

1. Set up your modem for dial-in access. See Section 4.3.2 in Network Administration for more information.

2. Edit the /etc/passwd file and create a dedicated entry for a PPP user. For the login shell field, specify /usr/sbin/startppp; for example:

   ppp1:password:10:20:Remote PPP User:/usr/users/guest:/usr/sbin/startppp
   

3. Edit the /etc/inittab file and create an entry for each terminal device that is to run PPP. For example:

   modem:3:respawn:/usr/sbin/getty /dev/tty00 M38400 vt100
   

   See the inittab(4) reference page for more information.

4. Issue the init q command to start the getty process immediately.

5. If the dial-in system is going to be a gateway for the dial-out system to reach other systems on the LAN, the dial-in system must be configured as an IP router and must also run gated. Edit the /etc/gated.conf file and delete the nobroadcast option (if specified) in the rip statement. See Chapter 2 of Network Administration for basic network setup information and the gated.conf(4) reference page for gated options.

6. Edit the /etc/ppp/options file and include the following pppd options required to support dial-in access for all remote users:

   netmask dd.dd.dd.dd  [1]
   proxyarp  [2]
   crtscts  [3]
   asyncmap 0  [4]
   :remote_ip_address  [5]
   debug  [6]
   

   1. Sets the interface netmask to the specified value. [Return to example]

   2. Adds an entry to the local system's Address Resolution Protocol (ARP) table that contains the IP address of the remote system and the Ethernet address of the local system. This is not necessary if gated is running. [Return to example]

   3. Enables hardware flow control for the serial port. [Return to example]

   4. If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example]

   5. Specifies an IP address for the remote system. [Return to example]

   If you want to specify options for each individual serial port, create a /etc/ppp/options.ttyxx file and include the remote IP address and any other options that apply to that specific serial port. See the pppd(8) reference page for a complete list of pppd options.

7. After an incoming call is received and a connection established, startppp runs in the background. The process ID is logged in the /etc/ppp/pppxx.pid file.

8. Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file.

If any problems occur while using PPP, see Chapter 13 in Network Administration.

7.3    System Administration Guide

The following notes describe changes to the System Administration guide.

---

7.3.1    Hard Limit for File System Quotas

In the System Administration guide, file system hard and soft quota limits are discussed in:

• Section 6.7.3.1, Hard and Soft Quota Limits for the UFS File System

• Section 7.5, Managing File System and Fileset Quotas for the AdvFS File System

• Section 9.3.4, Setting File System Quotas for the UFS File System

None of these sections discuss the fact that a hard limit is one more unit (blocks, files, inodes) than will be allowed when the quota limit is active. The quota is up to, but not including the limit. For example, if you set a hard limit of 10,000 disk blocks for each user account in a file system, an account reaches the hard limit when 9,999 disk blocks have been allocated. If you want a maximum of 10,000 complete blocks for the user account, you must set the hard limit to 10,001.

---

7.3.2    Environmental Monitoring

In the Environmental Monitoring section, the System Administration guide incorrectly states:

When a fan failure is encountered, a message is broadcasted and an orderly shutdown ensues.

It should state:

When the cooling fan on an AlphaServer 1000A fails, the kernel logs the error, synchronizes the disks, then powers the system down. On all other fan failures, a hard shutdown ensues.

---

7.3.3    User Definable Messages in Environmental Monitoring

You can modify any messages broadcast or logged by the Environmental Monitoring utility. The messages are located in the following file:

/usr/share/sysman/envmon/EnvMon_UserDefinable_Msg.tcl

You must be root to edit this file. You can edit any message included in braces ({}). The instructions for editing this file are included in the comment (#) fields. Do not alter any other data in this file.

---

7.4    Assembly Language Programmer's Guide

The Assembly Language Programmer's Guide (Chapter 5) should include a description of the .rconst directive. This directive instructs the assembler to add subsequent data into the .rconst section. This behavior is similar to the .rdata directive, except that the entries cannot be relocatable.

---

7.5    Programming with ONC RPC

Sections 2.1.5 and 2.1.6 of the Programming with ONC RPC guide are correct only for a DIGITAL UNIX system. The code may not be portable to other UNIX systems.

If the client machine is not another DIGITAL UNIX system, copy the source code to the client. Check that the header calls are appropriate for the programming conventions on the client operating system and then compile the code locally.

---

7.6    Developing Applications for the Display PostScript System

The guide for Developing Applications for the Display PostScript System refers to a nonexistent example directory /usr/examples/dps. None of the examples specified in the documentation are provided.

---

7.7    Gate Daemon Configuration Guide

References to the Gate Daemon Configuration Guide in the Technical Overview and possibly other books are obsolete because this document has been removed from the DIGITAL UNIX V4.0D Documentation, Volume 1 CD-ROM. Information from the Gate Daemon Configuration Guide has been incorporated into the following reference pages: gated.conf(4), gated.control(4), gated.proto(4), gated_intro(7), and gated(8).

---

7.8    Online Help Volumes

The notes in this section refer to problems with the online help volumes.

For each of the SysMan applications, online help is available from the Help menu or from the Help button in the main window.

The online help contains:

• An overview of the capabilities of the application

• A set of tasks illustrating typical uses of the application

• A reference section that documents every window and dialog box in the application.

The Using Help item on the Help menu displays a help volume that explains how to use the online help.

The Help viewer has the following known problems:

• In some cases, the help viewer is not correctly initialized. As a result, it will sometimes exhibit the expected behavior the second time an action is taken, but not the first time.

  For example, the first time a quick help dialog box displays a reference page, the Backtrack button may be enabled even though there is no place to which to backtrack. If the dialog box is closed and then opened again, the Backtrack button is dimmed.

• Similarly, if a request for on-item help displays the correct help, but one line has scrolled off the top, the online help will typically be displayed in exactly the right position when the on-item help request is repeated.

---

7.8.1    General Problems

The following known problems occur in the online help:

• The Appearance menu is not consistently documented.

  In the Archiver, License Manager, and System Information applications, there is an Appearance item on one of the menus. The item should offer three options: Text Only, Large Icon, and Small Icon. In some help volumes, not all of these are documented.

• Some links from one help volume to another are displayed in a new view.

  There are a few links from one help volume to another that appear in a new help viewer window. In some situations, a distracting proliferation of help viewer windows can result.

  You can get a new view when you want one using the New Window item on the File menu in the help viewer.

---

7.8.2    Integration

The SysMan configuration applications on-item help does not work on the items in the menu bar.

In all the SysMan applications, the keyboard method of getting on-item help does not work on the Help menu.

---

7.8.3    Update Path in Installation Online Help Is Incorrect

The update installation path shown in the installation online help is not correct. The Preinstall Review List in the installation online help should state:

Your system must be running DIGITAL UNIX operating system Version
4.0A, Version 4.0B, or Version 4.0C in order to update to
DIGITAL UNIX Version 4.0D.

---

7.8.4    Help Volumes by Application

The following problems apply only to help in specific applications:

• Kernel Tuner

  The Kernel Tuner application records its changes immediately, so if a system failure occurs while the Kernel Tuner is running, any boot-time changes will take effect the next time the system boots. If the /etc/sysconfigtab file contains invalid values, you can enter the following command at the boot prompt to boot with default values:

  boot -fl c
  

• Display Window

  The help volume for Display Window has opening instructions that show how to access the application from the CDE Application Manager. These should show that the Display Window icon appears in two groups.

• Network Configuration

  The names of the gated, joind, routed, and rwhod daemons are misspelled in the online help volume.

  In the Configuring Interfaces dialog box, the fields under To Obtain IP Address are relevant for all interfaces.

• Printer Configuration

  In the Local Printer Settings dialog box and the Remote Printer Settings dialog box, the aliases in the Printer Aliases field must be separated by vertical bars because spaces are allowed in an alias.

• Shutdown

  The /usr/sbin/shutdown command now sends the Shutdown Message each time a reminder is sent of the time remaining before the system is shut down.

  The /etc/nologin file is not created until immediately before the shutdown occurs.

  System shutdown messages are sent to all users that are locally or remotely logged in to the system being shut down. Additionally, if the "Broadcast to NFS Clients" option is selected, shutdown messages are broadcast to all hosts that are NFS clients of the system being shut down.

• Disk Configuration

  The following corrected definitions replace the definitions in the glossary for Disk Configuration.

  • Skew

    A deviation from a reference direction, either by design or in response to lateral forces.

  • Track skew

    On a disk, the sector skew per track. The skew is the angle that sector 0 of the track changes from an imaginary radius line, due to a nonuniform number of sectors per track.

• BIND Configuration

  The following corrected definitions replace the definitions in the glossary for BIND Configuration:

  • BIND client

    A system that queries a BIND server for host name and address information, interprets the responses, and passes the information to requesting applications.

  • BIND server

    An authoritative source for information about one or more zones. It either maintains the master copy of the hosts database for the zone or obtains the information required to serve the hosts database from another server.

  • DCE

    Distributed Computing Environment. The capabilities of DCE are defined by the Open Software Foundation (OSF).

  • DCE cell

    A logical group of systems that share services offered by DCE.

  • DCE server

    The server in a DCE cell.

  • service type

    In BIND Configuration, the available service types are BIND client and BIND server. The service type determines whether a system is configured to be a BIND client or a BIND server.