Filename: HOWTO_Set_Up_a_New_JNOS_System

Revised: 26-Jan-2012 at 09:26 by Michael Fox, N6MEF

This document is intended to be a quick, cheat-sheet or checklist of what to do when setting up a new Santa Clara County JNOS node. It is  intended to act as a reminder to even experienced JNOS users to insure that the node is created consistent with the county standard. Consult Linux or JNOS documentation for more details on how to perform various functions.

Setup BIOS

The county systems have the Phoenix Award BIOS v6. For other BIOS types or versions, look for similar settings.

Standard CMOS Features:

Drive A None (the county systems have no floppy drive)
Halt On All, but Keyboard

Advanced BIOS Features:
Quick Power On Self Test Enabled
First Boot Device CDROM
Second Boot Device Hard Disk
Third Boot Device Removable
BootUp Floppy Seek Disabled

Integrated Peripherals
Onboard Device Function

USB Keyboard Legacy Support Enabled
USB Mouse Legacy Support Enabled
PWR Status after PWR Failure Former status

Power Management

ACPI Suspend Type S3(STR)
Power Management User Defined

Video Off Method DPMS
Video Off in Suspend No
Suspend Mode Disabled

PC Health Status

Shutdown Temperature 70*C/158*F
CPU Thermal-Throttling Enabled
CPU Thermal-Throttling Temp 60*C
CPU Thermal-Throttling Duty 50%

Smart FAN Configurations

CPUFAN Smart Mode Enabled
CPUFAN Full-Speed Temp 50*C
CPUFAN Idle Temp 30*C
CPUFAN Idle-Speed Duty 60%

Create Ubuntu Install CD

The current version we are using is 10.04. This is a long term support version (LTS). The URL is http://releases.ubuntu.com/10.04/. In most cases, choose the 32-bit desktop version -- PC (Intel x86) desktop CD.

Install Ubuntu

Connect the system to a network with DHCP and Internet access. Place the CD in the CD drive and reboot. Follow the prompts to install Ubuntu.

During Install - Create user sccsysop

Create the user "sccsysop" (full name "SCCo SysOp") when asked during the installation process. It will receive administrative privileges. Do all of your work from this user account.

Do Not Enable Root User

The installation process does not ask about the root user. It is disabled by default. Run commands with sudo. Get a root shell with sudo -i.

Create Additional User

Create an additional user account for the main SysOp. This is a backup login in case the sccsysop account password is changed by one of the county sysops and then forgotten.

System > Administration > Users and Groups

Add
Enter name (First Last) and short name (login name)

Enter a password

Select the new user > Advanced Settings

User Privileges
Make sure "Administer the System" is checked

Advanced
Main Group sccsysop

Install Additional Applications

System > Administration > Synaptic Package Manager

Install the following additional applications using the Synaptic Package Manager. 

Firefox - Web browser (if not already installed)

gEdit - Graphical editor (if not installed)

gFTP - Graphical FTP application
- packages: gftp, gftp-common, gftp-gtk, gftp-text

mail - Simple command line mail agent
- packages: bsd-mailx
- Note: this will also install PostFix

Minicom - Terminal program for talking to TNCs
- packages: minicom (will also install lzrsz)

nautilus-gksu - Allows su while in the Nautilus file browser
- packages: nautilus-gksu

iproute - Additional IP routing commands
- packages: iproute, iproute-doc

NTP - Network Time Protocol daemon
- packages: ntp, ntp-doc, ntpdate

PuTTY - Terminal Emulator
- packages: putty, putty-tools

SSH - Secure shell
- packages: openssh-client, openssh-server

tofrodos - Converts between Unix and DOS formats
- packages: tofrodos

The PostFix install will ask two questions:

1) General type of mail configuration: Internet
2) System mail name: For now, accept whatever is displayed

Update Linux

System > Administration > Update Manager

The Update Manager may launch automatically. If not, run the Update Manager and "update" your system. Do NOT "upgrade" to a new version, such as to 10.10 or other, later release.

After the updates are completed. You will probably be asked to restart Linux. Do so.

Setup Static IP (typically)

System > Preferences > Network Connections

A static IP is important for being able to consistent connect to the box.

Enter your static IP address, mask and default router
Enter your DNS servers
Enter the search domains: scc-ares-races.org, ampr.org

Restart Linux after setting the static IP address.

(Optional) Add any USB Serial Ports as Needed

If you will be using USB-to-Serial port adapters, you need to plug them in now and determine their port name.

First, plug in a USB hub if you need one. A powered hub is recommended.

Next, one at a time, plug in the USB-to-serial adapter. After inserting each one, type "dmesg" in a terminal window. You will see output similar to:

[ 5351.649965] usb 2-1.3: new full speed USB device using ehci_hcd and address 5
[ 5351.743077] usb 2-1.3: configuration #1 chosen from 1 choice
[ 5351.743370] pl2303 2-1.3:1.0: pl2303 converter detected
[ 5351.745090] usb 2-1.3: pl2303 converter now attached to ttyUSB0

In this case, the USB-to-Serial adapter has been detected and assigned to port "ttyUSB0".

Mark the adapter with the port name and don't move it. Moving around USB devices can lead to them being assigned to different ports.

Repeat for any additional adapters.

Setup Minicom and Verify Access to Serial Ports

Start up minicom in setup mode with: sudo minicom -s

Configure minicom parameters as follows:

Serial port setup:

A - Serial device: /dev/ttyUSB0 (for example)
E - Bps/Par/Bits: 9600 8N1

Modem and Dialing

A - Init String: blank (backspace to delete default)
B - Reset string: blank (backspace to delete default)
K - Hang-up string: blank (backspace to delete default)

Save setup as:

ttyUSB0 (same as portname, without /dev/)

Exit

You should now be in terminal mode, connected to ttyUSB0 (for example).

If configured properly, you should get the "cmd>" prompt from your TNC.

Use CTRL-A, then "x" to exit.

Repeat for any additional ports and save the configurations for future use.

The files are saved to: /etc/minirc.<portname>. For the example above, the configuration would be saved as: /etc/minirc.ttyUSB0

To start up minicom with a saved configuration: sudo minicom ttyUSB0

Set Up NTP Servers

If NTP servers are available, either locally or via the Internet, you should set up NTP. 

System > Administration > Time and Date

If connected to the Internet, use the following servers:

0.us.pool.ntp.org
1.us.pool.ntp.org
2.us.pool.ntp.org
3.us.pool.ntp.org

If connected to an independent network with its own NTP servers, you can set up those servers instead of the pool servers. 

Restart Linux. Verify synchronization with ntpq -n -p. You should see the servers that you configured. Note that the pool servers will have different IP addresses at different times.

Set Up Power Management

System > Preferences > Power Management

On AC Power
Actions: Put computer to sleep when inactive for NEVER
Spin down hard disks when possible Checked
Display: Put display to sleep when inactive for 30 min

General

Actions: When the power button is pressed Shutdown
Actions: When the suspend button is pressed Suspend

Set Up Terminal Window

Applications > Accessories > Terminal

Terminal > 80x24
Edit > Keyboard Shortcuts

Enable the menu shortcut key (F10) uncheck (used by JNOS)

Help > Contents Alt-F1 (F1 used by JNOS)

Set Up Firefox Browser

Edit > Preferences

Select "Always ask me where to save files"

Set Up the System Menus

System > Preferences > Main Menu

Check the following menu choices:

Graphics: Document Viewer
Other: File Manager
System Tools: File Browser
GDebi Package Installer

Create the main JNOS directory

Create a directory for JNOS. The "standard" location is /opt/jnos.

sudo mkdir /opt/jnos
sudo chown sccsysop /opt/jnos
sudo chgrp sccsysop /opt/jnos

Set Up the File Browser

Places > Computer
Edit > Preferences

Default View List View
List Columns: add: Owner, Group, Permissions

Create a shortcut in the Nautilus File Browser for the jnos directory:

Navigate to the /opt/jnos directory.

Bookmarks > Add Bookmark

[OPTIONAL] Set Up DNS

Depending on your situation, it may make sense to make your Linux machine a DNS server. DNS architecture is beyond the scope of this document. If you want to set up Linux for DNS, you may want to do it now so that your JNOS configuration can include it. Otherwise, you can add it later and then update the JNOS configuration.

Create the Main JNOS Subdirectories

cd /opt/jnos
mkdir binaries
mkdir docs
mkdir help
mkdir spool
mkdir spool/help
mkdir logs
mkdir templfiles
mkdir utils

Make sure owner and group is sccsysop for all jnos sub-directories

Obtain an IP Address for JNOS

JNOS will need its own IP address, separate from the address used for the Linux Ethernet interface. If you don't plan to connect JNOS to the AMPRnet, you can use any private address you want. Private address ranges are:

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

If you plan to connect JNOS to the AMPRnet, you will eventually need to obtain an address in the 44.0.0.0/8 address space. So, you might as well do it now.

Contact the AMPR.ORG address coordinator for your region. The current coordinator for Silicon Valley is: Dan Curry, K6DLC - [email protected]

Connect to FTP Server and Copy JNOS Files to Local Machine

Use gFTP to connect to www.scc-ares-race.org.

The "jnos" directory contains the JNOS files and is organized like the directories created above.

JNOS Binary:

Go to <ftp-server>:jnos/binaries/JNOS_Application/Current_Stable

Copy the file located there to the local /opt/jnos/binaries directory

JNOS Docs:

Go to <ftp-server>:jnos/docs

Copy the files located there to the local /opt/jnos/docs directory

JNOS Help:

Go to <ftp-server>:jnos/help

Copy the jnoshelpfiles.tar archive located there to the local /opt/jnos/help directory

MBOX Help:

Go to <ftp-server>:jnos/help

Copy the mboxhelpfiles.tar archive located there to the local

/opt/jnos/spool/help directory

JNOS Templfiles:

Go to <ftp-server>:jnos/templfiles/Current_Stable

Copy the tar archive located there to the local /opt/jnos/templfiles dir.

JNOS Utilities:

Go to <ftp-server>:jnos/utils

Copy the files located there to the local /opt/jnos/utils directory

Set Up JNOS Binary

cd /opt/jnos/binaries

We'll call the current JNOS binary filename: <current-jnos-ver>

Make sure it has permissions 0755: sudo chmod 0755 <current-jnos-ver>

Change to the main JNOS directory:

cd /opt/jnos

List the binaries directory so you see the name of the file you will link:

ls binaries

Create the link:

ln -s binaries/<current-jnos-ver> jnos.exe

The JNOS startup scripts reference jnos.exe. This link allows you to switch the version of JNOS by changing the link, rather than editing the scripts.

Set Up the Help Files

Untar the JNOS console help files.

cd /opt/jnos/help
tar -xvf jnoshelpfiles.tar
rm jnoshelpfiles.tar

You should now have many individual help files, one for each JNOS console command.

Untar the JNOS mbox help files.

cd /opt/jnos/spool/help
tar -xvf mboxhelpfiles.tar
rm mboxhelpfiles.tar

You should now have many individual help files, one for each JNOS mbox command.

Unpack the templfiles archive

Templfiles are the template files that are used to configure JNOS. We'll call the current templfiles filename: <current-templfiles>

Copy it to the main JNOS directory, untar, and then delete the copy:

cd /opt/jnos/templfiles
cp <current-templfiles> ..
cd ..
tar -xvf <current-templfiles>
rm <current-templfiles>

(Note that a copy still exists in the /opt/jnos/templfiles directory.)

Run the createfiles script

The createfiles script asks a series of questions about the configuration of your system and the creates all of the proper configuration files

You must be root to run createfiles so we will use the sudo command.

You will need to know the serial port names. For USB ports, this is typically "ttyUSB0", "ttyUSB1", etc. For real serial ports, this is typically "ttyS0", "ttyS1", etc.

>From the main jnos directory, run the createfiles script:

cd /opt/jnos
sudo ./createfiles

The script does not have any error handling. If you make a mistake, simply CTRL-C and start again.

Set Up the <node>.local File

When createfiles is run, a <node> name is chosen. The <node>.local file contains local configuration overrides that will differ from site to site.

Copy the sample.node.local file to <node>.local, where <node> is the name given to the node when createfiles was run.

cd /opt/jnos
sudo cp docs/sample.node.local <node>.local

Edit the <node>.local file:

-- Uncomment the trace commands that correspond to the active ports on your machine.
-- Uncomment and edit the line that defines the mailbox superuser password.

Set Up the <node>.<type>.routes File

If your configuration requires the addition of JNOS or linux routes which are dependent upon JNOS and the tun0 interface being up, you can add these routes here. The <node>.jnos.routes file contains local JNOS routes particular to your system. It must in JNOS command format. The <node>.linux.routes contains linux route commands and should only be used for routes that depend on the JNOS tun0 interface.

An example is when a JNOS system relies on services (mail, DNS, NTP, etc.) from a remote linux system. The JNOS system must be configured with a route to the remote linux system's IP address. The linux system must be configured with a route to the JNOS system via tun0.

Copy the sample.node.routes shell script to <node>.local where <node> is the name given to the node when createfiles was run.

cd /opt/jnos
sudo cp docs/sample.node.jnos.routes <node>.jnos.routes
sudo cp docs/sample.node.linux.routes <node>.linux.routes

Edit the <node>.routes shell script:

-- Uncomment existing lines if the apply to your particular system

-- Add additional lines as necessary

Set Up the access.rc File

These rules control access to JNOS interfaces and services.

Copy the sample file to the JNOS main directory.

cd /opt/jnos
sudo cp docs/sample.access.rc access.rc

Edit the file to substitute the proper IP addresses and to uncomment the lines that correspond to the interfaces configured in JNOS.

Set Up Log Maintenance

Copy the sample.logrotate.conf file in the JNOS docs directory to the logrotate configuration file directory:

sudo cp /opt/jnos/docs/sample.logrotate.conf /etc/logrotate.d/jnos

Make sure owner/group are root/root and permissions are 0644.  This will cause daily log rotation of the trace files.

Copy the sample.cron.daily.jnos file to the proper directory to clean out old JNOS logs:

sudo cp /opt/jnos/docs/sample.cron.daily.jnos /etc/cron.daily/jnos

Make sure owner/group are root/root and permissions are 0755.  This will cause daily log pruning of the JNOS logs.

Set Up the iptables firewall rules

You need to protect the radio net from unintended and illegal traffic from the LAN and you need to protect the LAN and your Linux host from traffic from the radio net. Two iptables scripts are provided. iptables.tun_config  assumes that anything originating from the Linux host or the LAN is safe.

iptables.inet_config does what iptables.tun_config does, plus it controls what is allowed to enter the Linux host from the LAN and what is allowed to be forwarded between the LAN and the radio net.

If your Ethernet interface is attached to a secure LAN, then:

cd /opt/jnos
cp docs/sample.iptables.tun_config iptables.tun_config
chmod 0744 iptables.tun_config

If your Ethernet interface is not attached to a secure LAN, then:

cd /opt/jnos
cp docs/sample.iptables.inet_config iptables.inet_config
chmod 0744 iptables.inet_config

If your system will be acting as an AMPRnet gateway, then

cd /opt/jnos
cp docs/sample.iptables.gw_config iptables.gw_config
chmod 0744 iptables.gw_config

Adjust to suite your specific needs. CAREFULLY test any changes!

Start-up JNOS for the first time

Startup JNOS from the JNOS directory:

cd /opt/jnos

sudo ./jnos.exe

Your terminal window should convert to the JNOS console.

Do NOT resize this window - you will cause JNOS to panic and restart.

Press F9 to check the log. Make sure you can see beacons for each

port that you have active. A proper beacon will be look similar to:

Wed Nov 3 19:39:05 2010 - p144 sent:

KISS: Port 0 Data

AX25: N6MEF-1->ID UI pidText

0000 Santa Clara County ARES/RACES - Cupertino - CF Ver 120

If you see extraneous TNC commands mixed in with the output, there was a problem communicating with the TNC. Try exiting and starting again.

Return to the JNOS console by pressing F10.

Exit JNOS by typing "exit 0".

Configure Linux to Start JNOS at boot time

Use the sample.rc.local file located in the /opt/jnos/docs directory as an example to edit your /etc/rc.local file. Be careful. Your machine may have other entries in the rc.local file. /etc/rc.local should always exit 0 at the end.

Make sure the permissions allow execution: -rwxr-xr-x

Change the permissions if needed

sudo chmod 0755 /etc/rc.local

The sample file calls either iptables.inet_config or = iptables.tun_config, whichever exists and is executable in the main JNOS directory.

Next it calls the startup-jnos script. This script runs JNOS in a "screen" session which allows attaching to and detaching from the JNOS console from different terminal sessions. The screen command calls the start-loop script which will automatically restart JNOS if it terminates with other than a 0 exit code.

Setup JNOS onexit.nos Script (RECOMMENDED, but optional)

You can optionally add a script called "onexit.nos" in the main JNOS directory which will be executed by JNOS when it exits. The file must contain JNOS commands. One example use might tell users that the system is going down.

Note that this script will be executed each time JNOS exists. This include when JNOS is restarted within the start-loop script.

As a starting point, you can copy the sample.onexit.nos script from the docs directory. Be sure to make it readable:

cd opt/jnos

cp docs/sample.onexit.nos onexit.nos

chmod 0644 onexit.nos

Setup Exit Script (RECOMMENDED, but optional)

You can optionally add a script called "jnos.exit" in the main JNOS directory which will be executed by the start-loop script when JNOS is terminated.

The file must contain Linux shell script commands. One example use might be to bring all TNCs out of KISS mode.

Note that this script would only be executed when JNOS exits cleanly (exit code 0). Otherwise, JNOS is restarted without executing this script.

More specifically, these commands will NOT be executed if you restart JNOS from within the screen command, such as by using the "exit 99" command.

As a starting point, you can copy the sample.jnos.exit script from the docs directory.

cd opt/jnos

cp docs/sample.jnos.exit jnos.exit

Edit the script to send the proper commands to the proper interfaces.

Make sure it is executable:

chmod 0755 jnos.exit

Reboot Linux and Reconnect to JNOS

Restart your Linux system and log in as sccsysop.

Open a terminal session: Applications > Accessories > Terminal

Check that the screen session exists: sudo screen -ls

Reattach to the screen session (assuming only one exists): sudo screen -r

Detach from the screen session, but leave JNOS running: CTRL-A d

For more information on using the Linux "screen" command to access the JNOS console, see the "HOWTO_Screen_and_Putty_with_JNOS..." document in the /opt/jnos/docs directory.

Restarting JNOS While it is Running

The jnos-loop script which is run in the screen session will automatically restart JNOS if JNOS exits with anything other than a 0 (zero) return code.

To force JNOS to restart within the screen session, you can enter "exit = 99" at the JNOS console prompt.

Start JNOS After it Has Been Stopped

If you exit JNOS with "exit 0" (which exits the auto-restart loop script) and you wish to restart JNOS without rebooting Linux:

sudo /opt/jnos/startup-jnos

Next Steps

Read "HOWTO_Start_Up_JNOS" for more info on the start-up procedure.

Read "HOWTO_Screen_and_Putty_with_JNOS" for remote terminal session procedures.

---END---