5 Starting Up, Upgrading, and Shutting Down

This chapter covers the following topics:

• Installing the QNX RTP
• Initializing the system
• Upgrading the system
• Shutting the system down

Issues to be dealt with

[Author's Comments: This chapter should answer the following users' queries.How can I initialize an IDE Flash disk (or mechanical disk) to boot Neutrino 2.1 ? I try :
fdisk /dev/hd1
reboot
dinit -h -f img.ifs /dev/hd1t79
reboot without the mechanical disk and Flash disk as master: nothing...
The img.ifs boot OK on diskette.
The IDE flash disk boot OK with MS_DOS.
Flash disk: ATA Flash Storage SLATAFL512 SiliconTech, viewed as Hitachi
CVM1.1.1 by BIOS.Can I install on anything other than PCs running under Windows? Do we need different sets of instructions for different OS?What do I need to do to install this RTP (not configuration stuff--that comes next - ref) What do I need to do before I start? What do I need to know? What info do they need to have handy (e.g. size of hard disk and partition(s), type of hard disk controller (e.g. IDE, Adaptec 2940 SCSI), type and manufacturer of network card (e.g. Ethernet Novell NE2000)? what hardware/software do they need to have? What do I need in terms of system requirements? hard disk space, partition info?Can I get RTP from the web, by CD-ROM any other way? What is the difference between download and web versions? Why should I pay for a CD-ROM when I can get a free download? I can download and install under Windows, any other OS? )What do I get? What do I do with it? How long does it take to install? How do I know where everything is? (add some suggestions for locating files)]

Installing the QNX RTP

[Author's Comments: This section takes the user through the install process. E.g. What happens when they install? e.g. This program creates a directory structure, copies the software to your hard disk, and then builds an OS boot image configured according to information you provide during the installation process.)]

You'll know when you have finished the install because the system prompts you to remove the CD-ROM and reboot the system.

Before you start

[Author's Comments: Add caution on Winmodem]

When you modify your system, there is always the possibility that you may break something. Make backups of current control files and make a boot disk before you start, just in case.

Installing from a web download

Click on the executable program you downloaded and follow the instructions on your screen.

[Author's Comments: From user's comment: According to the posted articles on the subject and to my experience, it would be necessary (I think) to discuss about the requirements to connect the package manager to the qnx web site through a proxy server. Up to now, I don't know what to say to my provider in order the proxy accepts to transfer Package manager login requests or I don't what, to download your patches. @@@note no longer applicable since patch A )]

Installing from a CD-ROM

Insert the CD into the CD-ROM drive: The install program should start automatically (if not, run Setup.exe) and you will see several options. Read the release notes first, then decide whether you want to install into a file in Windows or into a free disk partition. Select the method you want, then follow the screen instructions.

Troubleshooting installation problems

[Author's Comments: User's comments: I had trouble installing RTP from the CD (created from downloaded ISO image); booting from the CD, and from the floppy it created--get Unable to access /cd//boot/fs--what does this mean?)]

Initializing the system

If you have installed QNX RTP in Windows, you will be given the option of starting Windows or RTP when you boot.

[Author's Comments: include something on alternate booting -- pressing the ESC key loads from /.altboot (?)]

Exactly what happens when I start RTP?

When RTP starts, the following sequence takes place:

• A boot image composed of several QNX 6 processes is loaded into main memory and then control is passed to a starting process.
• The starting process initializes the system, then transfers control to a process manager.
• The process manager (procnto) schedules other processes and manages memory protection and the pathname space (for more information on this manager, see Utilities Reference).

  Among other things, the process manager starts a boot utility (see diskboot in Utilities Reference) that sets up your filesystems and then starts a shell running a system initialization file. The system initialization file, sysinit, is an editable script containing commands that set up the services needed by your machine.

The boot image loaded when you start RTP is configured for a typical user; if you don't like it, you can change it to suit your needs.

Customizing your boot image

There are three ways you can change your boot image:

• You can change the boot options from a menu when you start RTP. See "Boot options"
• You could build a new image by creating a different buildfile or by modifying the simple script file input to the existing buildfile. See "Building a Custom OS Image"
• Or you may edit the system initialization file. See "Editing the system initialization file"

Boot options

After you start RTP, you can change your boot options by pressing the space bar when you are prompted. The resulting menu offers the following options:

F1     Enable Safe mode and use base QNX package only
F2     F1 plus use safe rc file
F3     F2 plus do not start photon
F4     F3 plus leave all other filesystems under /fs
F5     Start a debug shell after mounting filesystems
F6     Be Verbose
F7     Mount read-only partitions read/write if possible
F8     Enable a previous package configuration
F11    Enumertor disables
F12    Driver disables
Enter  Continue boot process 

Select the options you want from this list.

[Author's Comments: include what the option does and why and when you would use it]

[Author's Comments: (User's query: What is the default config? How can I change the default configuration?)]

[Author's Comments: Talk about safe boot: if things go really really bad, startup with F1 F2 F3 F4 F5 F6 as start up options -- you'll be able to get access to your drives. More than likely your /etc/system/package/packages file is invalid - to get access to it, you'll probably have to go to /fs/hdt???/etc/system/... but a safe one is located in /pkgs/base/safe-config/etc/system/package/packages]

Boot problems

If RTP won't boot, use the boot floppy disk you made to boot the system [Author's Comments: Can the user download a special boot floppy? If so, where from? Are there any recovery tools available? Ask tech supp]

Selecting command-line or GUI

The first time you start RTP, a dialog box will ask you to confirm the selected video settings. At the bottom of this dialog box, you can choose whether you want RTP to automatically start the Photon GUI (the default condition). If you want to start in command-line mode, uncheck this box.

If you want to start in command-line mode instead of Photon, but you do not want to re-install RTP, change this option by creating an empty file named nophoton in /etc/system/config. The system initialization script looks for this file when the system boots: if the system finds the file, it starts in command-line mode; if not, it starts Photon.

You'll need to log in as the superuser (root) to install additional software, customize your installation, or set up your network.

Editing the system initialization file

A system initialization file is simply an executable ASCII file that you can edit using a text editor. There may be more than one system initialization file on a machine. There is normally one common initialization file installed in all machines on a network and there may be one or more local files containing custom commands needed to set up the environment and services for a particular machine.

During a normal boot, RTP starts the common system initialization file sysinit located in the /etc/system directory. The main initialization file can call other script files as needed. Local system initialization files are usually kept in the /etc/rc.d directory. If you wanted to run extra commands at startup on a node, say to mount an NFS drive, you might create a script file named rc.local stored in the /etc/rc.d directory.

The initial sysinit file can execute code from other sysinit files using the dot command (for information on this command, see ksh in the Utilities Reference). E.g. in the typical sysinit file shown below, the following lines test for a local executable file, then execute the commands in the file in the current environment:

if test -x /etc/rc.d/rc.sysinit; then
  . /etc/rc.d/rc.sysinit


  

  

    

 





    

 If you want to edit a sysinit file, first make a backup copy of the latest working version. If you want to create a sysinit file, remember to make it executable before you use it (see how under chmod in Utilities Reference).



  




 

A typical sysinit file

The sysinit file for each machine contains the shell script that configures the services needed by that machine. Some services are commonly required by most machines.

Here's a typical sysinit shell script with some added explanations of the code (lines beginning with # are comments in the sysinit code):

Being able to understand shell scripts is important because they are used throughout RTP for managing the system. RTP uses a public domain version of the Korn shell. The Korn shell command interpreter (see Utilities Reference) sets the rules for the code used in shell scripts and interactive commands.

#This is the first script run by the system. It should
#start any systems services that would be in a monolithic
# *nix kernel. It finishes by "exec"ing into "init" 

First, tell the system where to look for commands and dot files:

# Change the path to get everything from the /bin and /sbin
export PATH=/sbin:/usr/sbin:/bin:/usr/bin 

Set up some important variables as integers:

#These are integers
typeset -i VERBOSE SAFEMODE NO_ETC  

Declare but do not export these environment variables: [Author's Comments: explain why not]

# Don't pass on these environment vars...
typeset +x BOOTSRC SAFEMODE VERBOSE ROOTDEV NO_ETC 

[Author's Comments: For a list of defined environment variables, see where?]

If verbose mode has been selected as a boot option, display these variables with their values:

# Display some info if requested
if test 0$VERBOSE -ge 1; then
  print BOOT		SRC=$BOOTSRC
  print SAFEMODE=$SAFEMODE
  print VERBOSE=$VERBOSE
  print ROOTDEV=$ROOTDEV
  print NO_ETC=$NO_ETC
  if test 0$VERBOSE -ge 2; then
    set -x
  fi
  sleep 2
fi 

Start the system logger unless it is already started (for more information on slogger, see the Utilities Reference). If you look up ksh to find out what this strange-looking test is doing, you won't make much sense of it: it seems to be asking whether /dev/slog is the same file as /dev/slog. Huh? Don't start doubting your sanity, this is just a device to check for the presence of something that might look like a file but may, in fact, just represent a pathname. It's only a safer way of checking whether slogger is running.

# Start the slog resmgr
if ! test /dev/slog -ef /dev/slog; then
   slogger
fi 

If the pipe manager has not been started, start it; if it still hasn't started after a minute, tell the user, start a new shell, and display error and a warning messages:

[Author's Comments: explain what the pipe manager does]

# Start the pipe manager. It is needed for sub-shelling...
if ! test /dev/pipe -ef /dev/pipe; then
  if pipe; then
    typeset -i i=0
    while test $i -lt 60 -a ! /dev/pipe -ef /dev/pipe ; do
      sleep 1;
      let i=i+1;
    done
  unset i
  fi
  if ! test /dev/pipe -ef /dev/pipe; then
    print Unable to start pipe manager...
    exec sh
    exec fesh
  fi
fi 

[Author's Comments: explain how carrying out the exec sh and exec fesh brings up a tcgetpgrp() error message and a warning]

If the system is not running in safe mode and is booting for the first time, the following code runs the script file rc.setup-once. This script checks for, and creates if necessary, essential directories, a swapfile, and a configuration file for the package manager, fs-pkg. It also creates the initial search database for the Helpviewer. For more information on the package file system, See "Using Package Manager"

The line TZ=$(cat /etc/TIMEZONE 2 >/dev/null copies the contents of /etc/timezone to the TZ variable; it also redirects the standard error output (2) to /dev/null (basically, nowhere), so that errors (e.g. file not found) are not put into TZ as well.

The setconf utility is used to set environment variables (in this case CS_TIMEZONE) that are used to configure the system.

[Author's Comments: add the code and explanation for rc.setup-once as well?]

# If there is no packages file, the system is just starting
# for the first time. Run rc.setup-once to fix any problems
# with the root filesystem, and extract any setup information
# to seed the initial files...
if test 0$SAFEMODE -eq 0 -a ! -r /etc/system/package/packages; then
# Must use a "." so the local vars are inherited (e.g. $ROOTDEV)
  . /etc/rc.d/rc.setup-once
fi
# Setup timezone (this should set confstr(CS_TIMEZONE) in the future)
if test -z "$TZ"; then
  TZ=$(cat /etc/TIMEZONE 2 >/dev/null)
  if test -z "$TZ"; then
    TZ=UTC
  fi
fi export TZ
setconf CS_TIMEZONE $TZ 

UTC stands for Coordinated Universal Time (was GMT)

Set the real time clock to the time of the system hardware clock according to local time, not UTC:

# Setup the realtime clock (usually if the rtc is localtime)
if test -x /etc/rc.d/rc.rtc; then
  . /etc/rc.d/rc.rtc
fi

# If no hostname is configured, look in /etc/HOSTNAME
HOSTNAME=$(hostname -s) 
if test "$HOSTNAME" == localhost; then
  if test -r /etc/HOSTNAME; then
    hostname $(cat /etc/HOSTNAME)
    HOSTNAME=$(hostname -s)
  fi
fi 

Another system initialization script, rc.devices, starts enum-devices, a utility that manages device enumeration; this utility spawns enumerators as required to find all the devices present on your system. QNX 6 stores information about the devices it can support in configuration files in the /etc/system/enum/devices/ directory. The device enumeration manager uses this information to check and start the device drivers your system requires.

# Enumerate the devices...
if test 0$VERBOSE -ge 2; then
  verbose=-v
fi
/etc/rc.d/rc.devices $verbose
unset verbose
# If there is a swap file, and rc.setup didn't already start it
# then enable swap file
if test ! "$swap" == on -a -r /.swapfile; then
  swapctl -a/.swapfile
fi

unset swap
# Clean up internal vars
unset HOSTNAME devices verbose
if test 0$VERBOSE -ge 1; then
  sleep 5
fi 

If the rc.sysinit script exists [Author's Comments: why would it exist? would the user create it? if so, why?] , allow it to take over from this initial system initialization script to set some more system variables; if it doesn't, display some error messages, warn the user, start a new shell, and then hand over control to it. If a new shell cannot be started, display a final error message:

# Run the system initialization script
if test -x /etc/rc.d/rc.sysinit; then
. /etc/rc.d/rc.sysinit
fi
print Unable to run rc.sysinit, starting a shell
exec sh
exec fesh
print Really can't do anything... 

This script ends by trying to start sh, the full Korn shell. If sh starts, it replaces this script; if sh fails to start, this script tries to start the fat embedded shell, fesh. If fesh fails to start, the user is informed of the failure.

Executing common commands

If several machines will be using a common set of commands, you can place the commands in a separate shell script and have the file executed via the dot (.) command. This is a special shell builtin command. The dot command reads and executes commands from a specified file, within the current environment. The search path contained in the environment variable PATH is used to find the directory containing this file.

For example, suppose you have a technical department and you want all of the machines in that department to start up using a set of common commands. You might create a file called techies and locate it in the /etc/system/ directory. This file would contain commands to be used by all the machines in your Technical Department. You would add the /etc/system/ directory to the PATH environment variable. The file could then be executed from within the sysinit file of each machine in that department with the following command:

. techies 

You could add other node-specific commands using the dot command line. For more information on the dot command, see the Utilities Reference.

Base-level services

The system initialization file for each machine provides the services needed by that machine. Most machines will need the services listed in this section.

Establishing the time zone

The following lines define the time zone and get the time from the realtime clock. For machines that boot from hard disk, these two lines should be the first in the sysinit file [Author's Comments: explain why] . For this example, we define our time zone as Eastern Standard Time (5 hours west of UTC) and use the initials EST to describe it, but you can specify what you want for time zone initials (see Library Reference for more information on global data and the TZ environment variable). EDT (Eastern Daylight Time) includes daylight saving time.

export TZ=EST5EDT
rtc hw 

For more information, See "Time zones and the realtime clock"

Starting the console and keyboard manager

The devc-con manager provides an interface to the console screen and keyboard. When devc-con starts, it creates and manages the devices for up to nine virtual consoles. A limited version of this utility, devc-tcon, is intended for memory-constrained systems; this version doesn't support special character editing (e.g. toggling insert mode or special erase characters). When devc-tcon starts, it creates and manages only the device /dev/con1. These console and keyboard managers are described in detail in the Utilities Reference (see devc-con).

Starting the floating-point emulator

By default, QNX 6 uses floating-point hardware in the CPU; if the CPU has no FPU, a shared object, fpemu.so, is loaded to provide support for floating-point emulation (see Utilities Reference, fpemu). An option in the Neutrino microkernel and process manager can force floating-point emulation (see Utilities Reference, procnto).

Starting a terminal daemon

The tinit utility initializes a terminal (see Utilities Reference, tinit). It invokes login (or phlogin if you specify the -p option) on the console(s) and serial terminals. The tinit utility runs as a background process, and is nearly always started in a local sysinit file.

Optional services

You can add many other services to your sysinit file. You should add these services in sysinit just before the line containing the tinit command. The examples below show some commonly used optional services. Note that these utilities typically support command-line options to modify their behavior; the options available for each utility are explained in Utilities Reference.

Setting environment variables

Processes started in the sysinit file inherit their environment variables. The general syntax of an environment variable definition is as follows:

export [parameter[=value]] 

where parameter is the name of the environment variable (conventionally in uppercase, such as TERM for terminal type or TZ for time zone), and value is the setting. For more information on export, see ksh in the Utilities Reference.

Starting a floppy driver

The floppy disk driver called by your sysinit file auto detects standard interfaces; you may need to specify your floppy disk port, IRQ and DMA channel if they are different from the defaults (see devb-fdc in Utilities Reference).

If you want to access the floppy as a non-QNX 6 filesystem, use the appropriate fs-* shared object (see Utilities Reference, under the appropriate fs-*.so for details of the different filesystem managers provided).

Starting a CD-ROM filesystem

To access files on a CD, you'll need to run the fs-cd.so shared object; this is a filesystem manager which supports ISO-9660, the standard for CD-ROM filesystems, as well as the Rock Ridge extensions. It's automatically loaded by the devb-* drivers when mounting an ISO-9660 filesystem. See fs-cd.so in Utilities Reference for more information.

Starting a DOS filesystem

If you need to access DOS floppies and partitions, you'll have to start a DOS filesystem. The fs-dos.so shared object lets you mount FAT12, FAT16, and FAT32 DOS filesystems under QNX 6; the devb-* drivers automatically load this shared object when mounting a DOS filesystem (see fs-dos.so in Utilities Reference).

Starting TCP/IP

RTP supports TCP/IP with two different stacks: a tiny stack (see Utilities Reference, npm-ttcpip.so) and a full BSD 4.4 TCP/IP stack (see Utilities Reference, npm-tcpip.so). The tiny stack is meant for resource-constrained applications where it is not necessary to have all TCP/IP services present; the limitations of the tiny stack are listed in the Utilities Reference.

On startup, the tiny stack is loaded by default. You can change the default to the full stack by editing /etc/system/enum/include/net: change pttcpip to ptcpip.

If you run io-net from the command line, simply specify ptcpip instead of pttcpip, e.g.:

io-net -dne2000 -ptcpip 

Speeding up your mouse

The inputtrap utility probes for input devices and starts the input manager, devi-hirun. Optionally, you may specify a different manager by using a trap file; see Utilities Reference, devi-hirun for details.

If you want to make your mouse run faster, first find the command line for the current input driver:

[Author's Comments: this is the method given in the knowledge base but it doesn't always work, check out the coming GUI method when available]

# ps | grep devi 

The command output is in the form of (thread id, parent thread id, command line), e.g.

4333600 1  devi-hirun kbd fd -d/dev/kbd msoft fd -d /dev/ser1 

Highlight the third field (beginning with devi-hirun) with the mouse, copy it, and then paste it on a new command line at the shell. Before invoking this command, add an option:

# devi-hirun kbd fd -d/dev/kbd msoft fd -d /dev/ser1 rel -G 3 

After you enter this command, your mouse will be three times more responsive. This option is described in the Utilities Reference, see devi-hirun.

Then kill the old input driver by thread number, e.g.

# kill -9 4333600 

where -9 signifies that this kill command cannot normally be stopped and 4333600 is the PID of the target process.

International keyboard support

The default keyboard setting is for the 101-key US keyboard. You can change the type of keyboard using the Photon User's Configuration dialog box. To display this box:

• Type pi from the command line, or
• Click the Localization icon on the Photon desktop.

Click the Keyboard tab, then select the keyboard layout you want, and then click Apply.

Time zones and the realtime clock

[Author's Comments: Check that this works in Nto]

It's important that the correct date, time, and time zone information is established early during initialization. These values should be set in the first line of your sysinit file [Author's Comments: check and correlate this to the earlier info] . The install program assumes that your hardware clock has a valid date and time and asks you for the time zone information [Author's Comments: where is install explained?] .

Valid dates on an RTP system range from January 1970 to January 2038. The internal date and time representation reaches its maximum value in 2038. If your system must operate past 2038 and there's no way for the system to be upgraded or modified in the field, you'll have to take special care with system dates (contact QNX for help with this).

Internally, RTP uses Coordinated Universal Time (UTC), sometimes called Greenwich Mean Time. Applications and utilities convert to local time by using information from the TZ time zone environment variable.

If the time zone environment variable TZ isn't set, RTP assumes that your local time is the same as North American Eastern Standard Time with current Daylight Saving Time (EST5EDT). If you wish to transfer files to another system in a different time zone, the dates on the transferred files are shifted by the difference between the two time zones.

Establishing the time zone

The time zone information should be established before the current date and time is set. If the realtime clock in your computer has been set to local time, RTP needs the time zone information in order to derive UTC.

In the following example, the time zone and the time change rules are set for Eastern Standard Time in North America:

export TZ=EST5EDT4,M4.1.0/3,M10.5.0/3 

This is what the command line means:

This part of the command line:	Stands for:
export	The shell command to set an environment variable
TZ	The name of the environment variable
EST	Three or more letters used to designate the standard time zone (in this case, Eastern Standard Time)
5	The offset number of hours (default, +) to make standard time equal to UTC time (UTC = EST + 5 hours)
EDT	Three or more letters optionally used to designate the summer time or daylight saving time (Eastern Daylight Time)
4	The offset number of hours to make summer time equal to UTC time (UTC = EDT + 4 hours)
M4.1.0/3	The date and time to change from standard to summer time (in this case, EDT starts on the first Sunday of April at 3am)
M10.5.0/3	The date and time to change from summer to standard time (in this case, EDT ends on the last Sunday of October at 3am)

See Library Reference for more information on global data and the TZ environment variable.

Getting the date and time from the realtime clock

If you're booting from disk, you should follow the time zone rules in your sysinit file with the rtc utility to establish the current date and time from the realtime clock. The following two lines would accomplish this:

export TZ=EST5EDT4,M4.1.0/3,M10.5.0/3 
rtc hw 

You can set the realtime clock in your machine to either:

• UTC or
• local time.

We recommend that you use UTC. But if you're also running operating systems that assume the realtime clock is set to local time (e.g. DOS), you'll want to use the rtc utility with the local time (-l) option:

rtc -l hw  

When you use local time in the realtime clock, you'll have to manually change the value in the realtime clock when you switch to and from daylight saving time in locales where it's used.

If the time in your hardware clock is incorrect (perhaps the battery has been replaced), set the system time using the date utility, then set the realtime clock using the rtc utility with the -s option. For details, see the documentation for these utilities in the Utilities Reference.

If you're booting over the network...

If you boot over the network, the booting machine inherits the UTC time from its boot server. Therefore, you don't need to put this information in your sysinit file.

Upgrading the system

[Author's Comments: users' queries--How do I upgrade stuff? How do I know when I should upgrade? How can I find out what additional software there is?]

Check out the QNX Realtime Platform web site and use Package Manager to install updates and patches (see "Installing a package from QNX").

Installing new software

[Author's Comments: Add procedure for using the package manager to install software]

Uninstalling software

[Author's Comments: using the package manager to uninstall software)]

Shutting the system down

It's important to shut the system down properly; either of these two methods will shut the system down gracefully and safely:

• From the command line, type shutdown, or
• From Photon, click Launch/Shutdown and then click the appropriate option button in the resulting dialog box.