MediaWiki - User contributions [en]

HowTo Install VirtualBox

2025-06-01T17:36:10Z

Paul Blankenbaker:

= Installing VirtualBox on NST 42 =

To install and configuration VirtualBox on an NST system using packages found in the RPM Fusion library, start with the following prompt to an AI engine:

How would I add the RPM Fusion repository and then install VirtualBox onto an NST system that is based off of Fedora 42?

The AI should provide [https://chatgpt.com/share/683adc17-335c-8003-a535-fb15a16ca6bc clear instructions].

NOTE: If you have the KVM modules loaded, VirtualBox may complain with a "VirtualBox can't operate in VMX root mode, please disable the KVM kernel extension..." message. To work around this issue, first remove the KVM kernel modules:

sudo rmmod kvm_intel
sudo rmmod kvm

Then, restart VirtualBox.

= Installing VirtualBox 4.0 on a NST v2.13.0 System =

The following commands can be used to install VirtualBox onto a NST system (as of 2009-Oct-26 using v2.11.0 of the NST distribution).

yum -y install kernel-devel gcc
yum -y install VirtualBox-4.0

= Installing on a NST v2.11.0 System =

The following commands can be used to install VirtualBox onto a NST system (as of 2009-Oct-26 using v2.11.0 of the NST distribution).

yum -y install kernel-devel gcc
cd /etc/yum.repos.d
wget -nH http://download.virtualbox.org/virtualbox/rpm/fedora/virtualbox.repo
yum -y install VirtualBox-4.0

= After Installation =

== Add Users to vboxusers Group ==

For every user you want to grant access to VirtualBox, you should add that user account to the ''vboxusers'' group. This can be done through the ''Users and Groups'' GUI tool (under the ''System | Administration'' menu on a GNOME desktop), or by using a text editor and directly editing your ''/etc/group'' file. For example after adding users ''pat'' and ''dianne'', you should a line similar to the following line in your ''/etc/group'' file (you may see a number other than 512):

vboxusers:x:512:pat,dianne

'''Note''': If a user is logged in when you add them to the ''vboxusers'' group, make sure you have them logout and then back in before running VirtualBox.

== Adding Extension Packs ==

Oracle has introduced the concept of ''extension packs'' starting with the 4.0 release of VirtualBox. You should be able to find these extension pack(s) by googling for "''oracle vm virtualbox extension pack''". At the time of this writing, there was a single USB 2.0 extension pack available.

You must be logged in as the ''root'' user to install a extension pack. The following demonstrates the command used to install the USB 2.0 extension pack:

VirtualBox Oracle_VM_VirtualBox_Extension_Pack-4.0.2-69518.vbox-extpack

== Starting VirtualBox ==

From the GNOME desktop, you can find the ''Oracle VM VirtualBox'' launcher under the ''Applications | System Tools'' menu. Alternatively, you can start VirtualBox directly from the command line using the command:

VirtualBox

== Listing IP Addresses of Running Virtual Machines ==

VirtualBox makes it a bit tricky to find the IP address allocated to each of your running machines. The following short script makes use of the VBoxManage command to:

* Get a list of all the running VMs
* Look up the IP address associated with each running VM

Here is the script that runs on both Linux and Mac (save to a file named: ''VBoxListIps''):

#!/bin/bash
#
# List IP addresses of running VMs

# Create quoted array of VirtualBox running VMs (need quotes as
# VMs can have spaces in names)
eval "declare runningVms=($(VBoxManage list runningvms | \
sed -e 's,^$".*"$ {.*}$,\1,'))";

# Look up IP address for each VM

for vm in "${runningVms[@]}"; do
declare ip=$(VBoxManage guestproperty get "${vm}" "/VirtualBox/GuestInfo/Net/0/V4/IP" 2>/dev/null | awk -- '{ print $2; }');

printf "%-15s %s\n" "${ip}" "${vm}";
done

Here is an example of the output from the script on a system with three running virtual machines:

taco-e:Downloads pkb$ VBoxListIps
192.168.1.80 VaiDev6c
192.168.1.82 dev18-32
192.168.1.112 tlp-el6
taco-e:Downloads pkb$

== VirtualBox FAQ ==
See section: "'''[[NST_and_Virtual_Machines#VirtualBox_Frequently_Asked_Questions | VirtualBox Frequently Asked Questions]]'''"

= VirtualBox Automatically Starting Guest VMs =

Enabling guest VMs to start automatically at boot can be a challenge. It comes down to the following basic steps:

* Enabling the auto-start feature in VirtualBox
* Adding user accounts that you want give the auto-start capability to
* Each user account must then be configured and register the virtual machines that should be started at boot.

== Enabling the Auto-Start Feature ==

For NST 28 (and Fedora 28), you need to modify/create the ''/etc/vbox/vbox.cfg'' file with two parameters required for the auto-start feature (other Linux distributions may use the ''/etc/default/virtualbox'' configuration file).

VBOXAUTOSTART_DB=/etc/vbox
VBOXAUTOSTART_CONFIG=/etc/vbox/autostart.cfg

You will also need to enable the ''virtualbox-autostart.service'' at boot time so that registered virtual machines will be auto-started:

systemctl enable vboxautostart-service.service

== Allow User Accounts ==

Create the ''/etc/vbox/autostart.cfg'' file and add allow a specific user account (change USER shown below to the name of the user account to be enabled on your system):

default_policy = deny
USER = {
allow = true
}

Make sure that the user account is part of ''vboxusers'' group (if you are already logged into the USER account you should log out and back in after completing this step):

sudo usermod -aG vboxusers USER

Update permissions on the ''/etc/vbox'' configuration files as follows to permit the members of the ''vboxusers'' group sufficient privileges:

sudo chmod 1775 /etc/vbox
sudo chgrp vboxusers /etc/vbox /etc/vbox/autostart.cfg
sudo chmod 640 /etc/vbox/vbox.cfg /etc/vbox/autostart.cfg

== Users Then Register VMs ==

At this point you need to log in to the user account that will register a VM to start at boot time and run the following commands. Change the setting of "vm" to the name of the virtual machine you want to start at boot time (use "VBoxManage list vms" to get a list of virtual machines). You may need to stop the VM before modifying its auto-start properties.

VBoxManage setproperty autostartdbpath /etc/vbox # Only needs to be done once
vm=nst28-repo # USE NAME OF YOUR VM
VBoxManage modifyvm $vm --autostart-enabled on # Can be: <on|off>
VBoxManage modifyvm $vm --autostart-delay 30 # Have seen issues if delay is left at 0
VBoxManage modifyvm $vm --autostop-type acpishutdown # Can be: <disabled|savestate|poweroff|acpishutdown
VBoxManage showvminfo $vm # Auto-start options shown, not auto-stop

HowTo Install VirtualBox

2025-05-31T10:42:52Z

Paul Blankenbaker: Added instructions for NST 42 (and later)

= Installing VirtualBox on NST 42 =

To install and configuration VirtualBox on an NST system using packages found in the RPM Fusion library, start with the following prompt to an AI engine:

How would I add the RPM Fusion repository and then install VirtualBox onto an NST system that is based off of Fedora 42?

The AI should provide [https://chatgpt.com/share/683adc17-335c-8003-a535-fb15a16ca6bc clear instructions].

= Installing VirtualBox 4.0 on a NST v2.13.0 System =

The following commands can be used to install VirtualBox onto a NST system (as of 2009-Oct-26 using v2.11.0 of the NST distribution).

yum -y install kernel-devel gcc
yum -y install VirtualBox-4.0

= Installing on a NST v2.11.0 System =

The following commands can be used to install VirtualBox onto a NST system (as of 2009-Oct-26 using v2.11.0 of the NST distribution).

yum -y install kernel-devel gcc
cd /etc/yum.repos.d
wget -nH http://download.virtualbox.org/virtualbox/rpm/fedora/virtualbox.repo
yum -y install VirtualBox-4.0

= After Installation =

== Add Users to vboxusers Group ==

For every user you want to grant access to VirtualBox, you should add that user account to the ''vboxusers'' group. This can be done through the ''Users and Groups'' GUI tool (under the ''System | Administration'' menu on a GNOME desktop), or by using a text editor and directly editing your ''/etc/group'' file. For example after adding users ''pat'' and ''dianne'', you should a line similar to the following line in your ''/etc/group'' file (you may see a number other than 512):

vboxusers:x:512:pat,dianne

'''Note''': If a user is logged in when you add them to the ''vboxusers'' group, make sure you have them logout and then back in before running VirtualBox.

== Adding Extension Packs ==

Oracle has introduced the concept of ''extension packs'' starting with the 4.0 release of VirtualBox. You should be able to find these extension pack(s) by googling for "''oracle vm virtualbox extension pack''". At the time of this writing, there was a single USB 2.0 extension pack available.

You must be logged in as the ''root'' user to install a extension pack. The following demonstrates the command used to install the USB 2.0 extension pack:

VirtualBox Oracle_VM_VirtualBox_Extension_Pack-4.0.2-69518.vbox-extpack

== Starting VirtualBox ==

From the GNOME desktop, you can find the ''Oracle VM VirtualBox'' launcher under the ''Applications | System Tools'' menu. Alternatively, you can start VirtualBox directly from the command line using the command:

VirtualBox

== Listing IP Addresses of Running Virtual Machines ==

VirtualBox makes it a bit tricky to find the IP address allocated to each of your running machines. The following short script makes use of the VBoxManage command to:

* Get a list of all the running VMs
* Look up the IP address associated with each running VM

Here is the script that runs on both Linux and Mac (save to a file named: ''VBoxListIps''):

#!/bin/bash
#
# List IP addresses of running VMs

# Create quoted array of VirtualBox running VMs (need quotes as
# VMs can have spaces in names)
eval "declare runningVms=($(VBoxManage list runningvms | \
sed -e 's,^$".*"$ {.*}$,\1,'))";

# Look up IP address for each VM

for vm in "${runningVms[@]}"; do
declare ip=$(VBoxManage guestproperty get "${vm}" "/VirtualBox/GuestInfo/Net/0/V4/IP" 2>/dev/null | awk -- '{ print $2; }');

printf "%-15s %s\n" "${ip}" "${vm}";
done

Here is an example of the output from the script on a system with three running virtual machines:

taco-e:Downloads pkb$ VBoxListIps
192.168.1.80 VaiDev6c
192.168.1.82 dev18-32
192.168.1.112 tlp-el6
taco-e:Downloads pkb$

== VirtualBox FAQ ==
See section: "'''[[NST_and_Virtual_Machines#VirtualBox_Frequently_Asked_Questions | VirtualBox Frequently Asked Questions]]'''"

= VirtualBox Automatically Starting Guest VMs =

Enabling guest VMs to start automatically at boot can be a challenge. It comes down to the following basic steps:

* Enabling the auto-start feature in VirtualBox
* Adding user accounts that you want give the auto-start capability to
* Each user account must then be configured and register the virtual machines that should be started at boot.

== Enabling the Auto-Start Feature ==

For NST 28 (and Fedora 28), you need to modify/create the ''/etc/vbox/vbox.cfg'' file with two parameters required for the auto-start feature (other Linux distributions may use the ''/etc/default/virtualbox'' configuration file).

VBOXAUTOSTART_DB=/etc/vbox
VBOXAUTOSTART_CONFIG=/etc/vbox/autostart.cfg

You will also need to enable the ''virtualbox-autostart.service'' at boot time so that registered virtual machines will be auto-started:

systemctl enable vboxautostart-service.service

== Allow User Accounts ==

Create the ''/etc/vbox/autostart.cfg'' file and add allow a specific user account (change USER shown below to the name of the user account to be enabled on your system):

default_policy = deny
USER = {
allow = true
}

Make sure that the user account is part of ''vboxusers'' group (if you are already logged into the USER account you should log out and back in after completing this step):

sudo usermod -aG vboxusers USER

Update permissions on the ''/etc/vbox'' configuration files as follows to permit the members of the ''vboxusers'' group sufficient privileges:

sudo chmod 1775 /etc/vbox
sudo chgrp vboxusers /etc/vbox /etc/vbox/autostart.cfg
sudo chmod 640 /etc/vbox/vbox.cfg /etc/vbox/autostart.cfg

== Users Then Register VMs ==

At this point you need to log in to the user account that will register a VM to start at boot time and run the following commands. Change the setting of "vm" to the name of the virtual machine you want to start at boot time (use "VBoxManage list vms" to get a list of virtual machines). You may need to stop the VM before modifying its auto-start properties.

VBoxManage setproperty autostartdbpath /etc/vbox # Only needs to be done once
vm=nst28-repo # USE NAME OF YOUR VM
VBoxManage modifyvm $vm --autostart-enabled on # Can be: <on|off>
VBoxManage modifyvm $vm --autostart-delay 30 # Have seen issues if delay is left at 0
VBoxManage modifyvm $vm --autostop-type acpishutdown # Can be: <disabled|savestate|poweroff|acpishutdown
VBoxManage showvminfo $vm # Auto-start options shown, not auto-stop

HowTo Use Gmail API to send emails

2024-07-13T21:06:28Z

Paul Blankenbaker: Created page with "= Using Gmail API to send emails = You can find very specific details on how to use the [https://developers.google.com/gmail/api/guides Gmail API] for many different purposes. This page skips over a lot of the details and provides a quick reference on how to send an email using the [https://developers.google.com/gmail/api/guides Gmail API]. == Enable Gmail API == You will need to select or create a Google project and add the "Gmail API" to the list of APIs & Services..."

= Using Gmail API to send emails =

You can find very specific details on how to use the [https://developers.google.com/gmail/api/guides Gmail API] for many different purposes.

This page skips over a lot of the details and provides a quick reference on how to send an email using the [https://developers.google.com/gmail/api/guides Gmail API].

== Enable Gmail API ==

You will need to select or create a Google project and add the "Gmail API" to the list of APIs & Services panel as shown on the Google Cloud panel below:

[[File:Apis-and-services.png|800px|alt=APIs & Services panel shows that the Gmail API has been enabled for the project|APIs & Services panel shows that the Gmail API has been enabled for the project]]

== Download Oauth JSON Credentials ==

You will need to enable/add the Oauth client option on the credentials panel as shown below and then press the download button to download the credentials file.

[[File:Credentials-marked.png|800px|alt=Credentials panel to download the JSON credentials file necessary for initial authentication of script|Credentials panel to download the JSON credentials file necessary for initial authentication of script]]

You can use the following command to format the downloaded JSON file:

<pre>
cat ~/Downloads/client_secret_*.json | jq
</pre>

The output of the above command will produce something similar to the following (where "..." will contain values specific to your authentication):

‎<syntaxhighlight lang="json" line>
{
"installed": {
"client_id": "...",
"project_id": "...",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_secret": "...",
"redirect_uris": [
"http://localhost"
]
}
}
</syntaxhighlight>

= Sample Python Script =

The following python script (send-via-gmail-api.py) can be used to send emails.

‎<syntaxhighlight lang="python" line>
#!/usr/bin/python3
#
# NOTE: In order to run this you need to add the following packages to the system
#
# sudo dnf install python3-google-api-client python3-oauth2client

import base64
import httplib2
import oauth2client
import os
from email.mime.text import MIMEText
from googleapiclient.discovery import build
from oauth2client import client, tools, file

SCOPES = 'https://www.googleapis.com/auth/gmail.send'

# By default we will look for credentials files under ~/.local/credentials, you should set the permissions
# to this directory to 700
CREDENTIAL_DIR = os.getenv('CREDENTIALS_DIR', os.path.join(os.path.expanduser('~'), '.local', 'credentials'))

# You will need to download this JSON file from Google project that you have enabled the
# Gmail API on. NOTE: This is typically only needed to generate the limited scope credentials JSON
# file once at which point that is the only file that will typically be used when the script
# needs to present itself as legitimate when sending email messages out.

# You can export GOOGLE_PROJECT_SECRETS to the location of your credentials file to override default location
PROJECT_OAUTH_SECRET_FILE = os.getenv('GOOGLE_PROJECT_SECRETS', os.path.join(CREDENTIAL_DIR, 'email-project-secret.json'))
APPLICATION_NAME = 'Gmail API Python Send Email'

def get_credentials():
if not os.path.exists(CREDENTIAL_DIR):
os.makedirs(CREDENTIAL_DIR)
# Actual authorization file for our script with necessary scope set so we can send out email
credential_path = os.path.join(CREDENTIAL_DIR, "gmail-api-email-send.json")
credentials = False
store = oauth2client.file.Storage(credential_path)
if os.path.exists(credential_path):
credentials = store.get()
if not credentials or credentials.invalid:
# Authorization file needs to be (re)created, request a new one using project credentials
# IMPORTANT: When this occurs, you will need to interact with a browser to confirm that
# it is OK to allow the script to send emails on your behalf!
print(f"Need to update/create {credential_path}")
flow = client.flow_from_clientsecrets(PROJECT_OAUTH_SECRET_FILE, SCOPES)
flow.user_agent = APPLICATION_NAME
credentials = tools.run_flow(flow, store)
print(f"Stored credentials to {credential_path}")
return credentials

def send_email(service, sender, to, subject, message_text):
message = MIMEText(message_text, "html")
message['to'] = to
message['from'] = sender
message['subject'] = subject
raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode("utf-8")
message = {'raw': raw_message}
try:
message = service.users().messages().send(userId='me', body=message).execute()
print(f'Message sent, Id: {message["id"]}')
return message
except Exception as error:
print(f'An error occurred: {error}')
return None

if __name__ == '__main__':
credentials = get_credentials()
http = credentials.authorize(httplib2.Http())
service = build('gmail', 'v1', http=http)
send_email(service, 'FROM_USER@DOMAIN', 'TO_USER@DOMAIN', 'My Subject', '<p>My Email <b>Body</b></p>')
</syntaxhighlight>

Be aware of the following:
* The first time the script is run it will pull up a browser to confirm that you want to grant permission (this won't be required on subsequent runs).
* You will need to change the FROM_USER@DOMAIN and TO_USER@DOMAIN values at the end of the script to the email accounts that you want to test with.
* It expects to find the oauth credentials JSON file that you downloaded at $HOME/.local/credentials/email-project-secret.json (feel free to change).
* The initial authentication will create a new $HOME/.local/credentials/gmail-api-email-send.json file that will then be used during subsequent invocations.

== Install DNF Packages ==

The NST distribution does not have all of the Python packages required to run this script by default. You should be able to add the necessary packages via the
following command:

‎<syntaxhighlight lang="bash" line>
sudo dnf install python3-google-api-client python3-oauth2client
</syntaxhighlight>

If you are using a different operating system, you should be able to use "pip" to install the necessary python packages.

== Install Oauth JSON Credentials ==

Before running the script, you will need to install the project secrets file in the location that the script will attempt to read it from.

‎<syntaxhighlight lang="bash" line>
install -d -D -m 700 ~/.local/credentials
install -m 600 ~/Downloads/client_secret_*.json ~/.local/credentials/email-project-secret.json
</syntaxhighlight>

== Initial Run Confirmation ==

Try running the script initially by hand.

‎<syntaxhighlight lang="bash" line>
./send-via-gmail-api.py
</syntaxhighlight>

A web browser should appear and you will need to confirm that you want to grant permission to the script before it will be permitted to send emails.
Once successfully granted, you should see output similar to the following:

<pre>
[nst@nst-test ~]$ ./send-via-gmail-api.py
Need to update/create /home/nst/.local/credentials/gmail-api-email-send.json

Your browser has been opened to visit:

https://accounts.google.com/o/oauth2/auth?client_id=...

If your browser is on a different machine then exit and re-run this
application with the command-line parameter

--noauth_local_webserver

Authentication successful.
Stored credentials to /home/nst/.local/credentials/gmail-api-email-send.json
Message sent, Id: 190ade399aa9f639
</pre>

You should find that a new non-zero length credentials JSON file (gmail-api-email-send.json) has been created under your ~/.local/credentials directory:

<pre>
[nst@nst-test ~]$ ls -al ~/.local/credentials/
total 8
drwx------ 1 nst nst 100 Jul 13 16:58 .
drwx------ 1 nst nst 42 Jul 13 10:46 ..
-rw------- 1 nst nst 402 Jul 13 11:05 email-project-secret.json
-rw------- 1 nst nst 1410 Jul 13 16:58 gmail-api-email-send.json
[nst@nst-test ~]$
</pre>

== Subsequent Runs No Confirmation ==

Run the script again. Now that the system has been confirmed, subsequent runs should proceed without user interaction.

<pre>
[nst@nst-test ~]$ ./send-via-gmail-api.py
Message sent, Id: 190ade73471976a6
[nst@nst-test ~]$
</pre>

At this point you should see the emails showing up in your inbox.

File:Credentials-marked.png

2024-07-13T20:23:24Z

Paul Blankenbaker:

Google Cloud credentials panel for project where we want to download the JSON credentials from in order to have a script that can send emails using the Gmail API

File:Apis-and-services.png

2024-07-13T20:19:31Z

Paul Blankenbaker:

The Google Cloud administrative page for a sample project showing that the Gmail API has been enabled for the project.

HowTos

2024-07-13T20:13:46Z

Paul Blankenbaker:

* [[HowTo Adjust The Display Brightness On A Laptop In Console Mode Using The Command Line]]
* [[HowTo Adjust The Keyboard Backlight Brightness On A Laptop In Console Mode Using The Command Line]]
* [[HowTo Backup And Restore The Master Boot Record (MBR)]]

* [[HowTo BackupPC SSH Key Authentication Setup For rsync Transfer]]
* [[HowTo Change The LVM Volume Group Name That Includes The Root Partition]]
* [[HowTo Configure Apache SSL For davfs, subversion, etc.]]
* [[HowTo Configure and Run a Ring Buffer Capture Session Using: "nstringbufcap"]]
* [[HowTo Create A Patch File For A RPM]]
* [[HowTo Create A GPT Disk With EFI System And exFAT Partitions Using Parted]]
* [[HowTo Curl Examples]]
* [[HowTo Fix The rngd.service]]
* [[HowTo Determine If Hardware Virtualization Is Enabled]]
* [[HowTo Disable The "relatime" Method For File "atime" Updates]]
* [[HowTo Download From The Command Line Using: "wget"]]
* [[HowTo Dual Boot NST With Windows 8.1]]
* [[HowTo Enable The Gnome Sound Applet]]
* [[HowTo Generate a 3D Pie Chart of nDPI Detected Protocols]]
* [[HowTo Geolocate Data Using The NST WUI]]
* [[HowTo Headless Intel NUC vPro AMT]]
* [[HowTo Install Microsoft PowerShell]]
* [[HowTo Install The MATE (GNOME 2) Desktop]]
* [[HowTo Install VirtualBox]]
* [[HowTo Keep Processes Running After Logging Out Using: "setsid"]]
* [[HowTo Limit Remote Access To "ssh" Connections]]
* [[HowTo Monitor Network Traffic]]
* [[HowTo One Liners]]
* [[HowTo Perform A Security Audit With hping3 (DoS)]]
* [[HowTo Prevent A Laptop Lid Close Suspension]]
* [[HowTo Regenerate The TLS (SSL) Certificate For The NST WUI]]
* [[HowTo Remote Connect to a Mate Desktop Session Using the Vino Server]]
* [[HowTo Resize The "root" File System Using LVM]]
* [[HowTo Quickly Get A Project Started With Subversion]]
* [[HowTo Quickly Setup A VPN Using WireGuard On NST]]
* [[HowTo Put Multiple Live Images On One USB Memory Stick]]
* [[HowTo Recreate Grub Install And The Master Boot Record (MBR) If Corrupted]]
* [[HowTo Run A Script At Boot]]
* [[OpenVAS | HowTo Setup OpenVAS]]
* [[HowTo Setup An NST System With Multiple Network Interface Adapters Using: "nstnetcfg"]]
* [[HowTo Setup Guacamole]]
* [[HowTo Setup Suricata - A Simple Live Configuration]]
* [[HowTo Share A Terminal Session Using Screen]]
* [[HowTo Shutdown NST Using A USB Flash Drive Install For Relocation]]
* [[Upgrade to NST 20|HowTo Upgrade from NST 18 to NST 20]]
* [[HowTo Use an Android Phone as a GPSd Source]]
* [[HowTo Use A Touch Device (iPad) with NST]]
* [[HowTo Use Gmail API to send emails]]
* [[HowTo Use The NST CloudShark Upload Manager]]
* [[HowTo Use The NST Network Tools Widgets]]
* [[NST Mapping Tools | HowTo Use The NST Map Tools Widgets]]
* [[HowTo Use The NST Shell Command Console]]
* [[HowTo Use The NST WUI arp-scan Page To Quickly Locate Hosts]]
* [[HowTo Use The Scapy: Multi-Traceroute - MTR]]
* [[Console Output and Serial Terminals | HowTo Setup Console Output and Serial Terminals]]
* [[DVD_md5sum | HowTo Verify The Md5Sum On An DVD ISO]]
* [[HowTo Install NST 2.16 on an Asus Zenbook Prime]]

Commit and Publish HTML Updates

2024-05-12T18:53:19Z

Paul Blankenbaker:

Now that you have finalized the release information, you need to publish this information for the general public. In order to accomplish this, you will want to commit any modified files and then run: '''make docs-build-upload''' as shown below:

[root@nst-dev-32 repo]# svn commit

... typical commit output and comment editing ...

[root@nst-dev-32 repo]# make docs-build-upload SFUSER=ACCOUNT_NAME

... lots of output as documentation is built ...

[root@nst-dev-32 repo]#

Download And Verify MD5 Values

2024-05-12T17:37:38Z

Paul Blankenbaker:

* Go to the files area for the new release out at [https://sourceforge.net/projects/nst/files/NST/ SourceForge].

* Open the folder to the directory that you just copied the release files to.

* Click on the information icon to display the MD5 checksum values at SourceForge.

* Verify that the checksum values match what you computed earlier and put in the updated release manifest file.

Do a Sanity Check

2024-05-07T10:18:03Z

Paul Blankenbaker: /* Check Enabled Services */

Prior to creating a release, one should perform the following sanity checks.

Note: In order to perform all of the sanity checks, you will need BOTH your NST development system and a running NST probe.

== Commit ==

You should do a commit to ensure that you do not have any outstanding modifications.

svn commit

== Build Yum Repository ==

Run the following from the top level directory to make certain that you can build and update all the RPM files that make up the NST repository.

sudo dnf clean all
make repo-build

== Check Enabled Services ==

Make sure you boot a recent ISO image and verify that the expected services are enabled at boot time. Be aware that the '''sshd''' and '''httpd''' services will not be enabled or running until the '''nstpasswd''' command is run. Run the following command and review the output produced. NOTE: The output shown below was produced after booting the NST ISO in VirtualBox and selecting the ''Console'' target and running ''nstpasswd''.

[root@probe ~]# systemctl list-unit-files | grep "enabled " | grep service | sort
abrt-journal-core.service enabled enabled
abrt-oops.service enabled enabled
abrt-vmcore.service enabled enabled
abrt-xorg.service enabled enabled
accounts-daemon.service enabled enabled
dbus-daemon.service enabled enabled
dkms.service enabled enabled
getty@.service enabled enabled
import-state.service enabled enabled
irqbalance.service enabled enabled
lightdm.service enabled enabled
lvm2-monitor.service enabled enabled
mcelog.service enabled enabled
ModemManager.service enabled enabled
NetworkManager-dispatcher.service enabled enabled
NetworkManager.service enabled enabled
NetworkManager-wait-online.service enabled enabled
nstboot.service enabled enabled
nstwui.service enabled disabled
pmcd.service enabled enabled
pmie.service enabled enabled
pmlogger.service enabled enabled
rsyslog.service enabled enabled
rtkit-daemon.service enabled enabled
selinux-autorelabel-mark.service enabled enabled
smartd.service enabled enabled
sshd.service enabled disabled
sssd.service enabled enabled
switcheroo-control.service enabled enabled
systemd-boot-update.service enabled enabled
systemd-confext.service enabled enabled
systemd-homed-activate.service enabled disabled
systemd-homed.service enabled enabled
systemd-networkd-wait-online.service enabled enabled
systemd-network-generator.service enabled enabled
systemd-pstore.service enabled enabled
systemd-sysext.service enabled enabled
udisks2.service enabled enabled
upower.service enabled enabled
vboxservice.service enabled enabled
vgauthd.service enabled disabled
vmtoolsd.service enabled enabled
[root@probe ~]#

You might only see the ''vboxservice.service'' entry if you are running under VirtualBox.

== Verify That Documentation Builds ==

Make sure the ''docs'' directory builds. This is required to update the on-line version of the man pages for the release:

[root@dev repo]# cd docs
[root@dev docs]# make

== Run Automated Tests ==

Run the following from the top level to perform numerous checks on the running NST probe with the IP address specified.

make probe-check HOST=IP

There will be a LOT of output produced. A copy of the output will be saved to the file: "probe-check.log" which may be viewed using the command: "less -R probe-check.log". Make sure the file looks clean (or like you would expect). Make sure you aren't tempted to skip this step. We thought we were OK and skipped this step during the 1.8.1 release and ended up delivering a ISO image with a broken sym-link.

Manual Package Updates

2024-05-07T07:42:17Z

Paul Blankenbaker: Updated directions for arp-scan

= Package Data Files =

== arp-scan ==

Update the yum/pkgs/arp-scan/src/ieee-oui.txt included in the arp-scan package by:

* Use the "Update OUI" button in the settings panel on the NST WUI.
* Copy the updated /usr/share/arp-scan/ieee-oui.txt file from the NST system to the yum/pkgs/arp-scan/src/ieee-oui.txt location on the NST build system.
* Bump the release number in yum/pkgs/arp-scan/pkginfo.xml.
* Update the change log in yum/pkgs/arp-scan/template.spec.

= Check Package URLs =

There are many ''pkginfo.xml'' files which are associated with the RPM packages making up the NST yum repository. Each of these ''pkginfo.xml'' files will have two or more URLs. As time goes by these URLs may ''move'' and need to be updated. You can run the ''make url-check'' command from the ''yum'' directory to:

* Extract the URLs from each fo the ''pkginfo.xml'' files.
* Run the ''curl -head'' command on each of the extracted URLs.
* See '''ok''', '''skip''' or '''FAIL''' displayed on the screen next to each URL as it is checked.
* Create two log files: ''url-check.log'' and ''url-check-details.log''.

Here is a example of running the command:

[root@taco-dev32 dev]# cd yum
[root@taco-dev32 yum]# make url-check
[ok] file:///root/dev/yum/pkgs/ipsc/src/ipsc-0.4.3.tar.bz2
[ok] file:///root/dev/yum/pkgs/nst-disk-speed/src/seeker.c
[ok] file:///root/dev/yum/pkgs/smtpclient/src/smtpclient-1.0.0.tar.gz
[ok] file:///root/dev/yum/pkgs/tcptrack/src/tcptrack-1.4.2.tar.gz

... output continues as all URLs are checked ...

[root@taco-dev32 yum]#

If you just want to see the list of URLs with issues, you can run the following '''grep''' command on the generated log file:

[root@taco-dev32 yum]# grep -v ok url-check.log
[skip] git://github.com/gnumaniacs/netsniff-ng.git
[root@taco-dev32 yum]#

NOTE: The ''skip'' entries indicate protocols which '''curl''' is unable to handle and verification is skipped. If you would like to verify the skipped entries, you will need to do it manually.

= Check Date Change Logs =

Run the following command to verify that all change log dates in the spec files are good.

[nst28-repo@nst yum]$ make changelog-date-check
all - Changelog date(s) ok
[nst28-repo@nst yum]$

HowTo Create A Public Repo

2023-07-24T21:12:28Z

Paul Blankenbaker: Tweaks to make copy/paste easer

__TOC__
= '''Overview''' =
This page briefly shows example steps on how to create a Public Repo for selective RPMs. An example public repo creation for NST 38 will be shown hosted at a2host.

= '''Create Top Level Local Directory Paths For RPMs To Be Published''' =
These paths mimic that on the public repo server (e.g., a2host).

NSTREL=38
mkdir -p ~/f${NSTREL}/x86_64/noarch;
mkdir -p ~/f${NSTREL}/x86_64/x86_64;

= '''Copy RPM To Be Publish Over To These Directories''' =
Copy already created RPMs from the NST Pro Repo 38. This example includes RPMs: nstwui, nstwui-filesystem and snort.

cp ~/repo${NSTREL}/yum/repo/noarch/nstwui-${NSTREL}*.nst${NSTREL}.noarch.rpm ~/f${NSTREL}/x86_64/noarch;
cp ~/repo${NSTREL}/yum/repo/noarch/nstwui-filesystem-${NSTREL}*.nst${NSTREL}.noarch.rpm ~/f${NSTREL}/x86_64/noarch;

cp ~/repo${NSTREL}/yum/repo/x86_64/snort-*.nst${NSTREL}.x86_64.rpm ~/f${NSTREL}/x86_64/x86_64;

= '''Sign The RPMs''' =
Sign all new RPMs in the repo.

rpm --addsign /home/nst/f${NSTREL}/x86_64/noarch/nstwui-${NSTREL}*.nst${NSTREL}.noarch.rpm ~/f${NSTREL}/x86_64/noarch/nstwui-filesystem-${NSTREL}*.nst${NSTREL}.noarch.rpm ~/f${NSTREL}/x86_64/x86_64/snort-*.nst${NSTREL}.x86_64.rpm;

= '''Create The Repo''' =
Create a RPM repo under the NST home directory: "'''/home/nst/f${NSTREL}/x86_64'''"
createrepo -v ~/f${NSTREL}/x86_64;

= '''Upload Repo To The Public NST Repo Server''' =
Send the entire repo to the public NST repository.

rsync --delete -avh ~/f${NSTREL} a2:public_html/repo/nst;

Do a Sanity Check

2023-07-20T16:34:05Z

Paul Blankenbaker:

Prior to creating a release, one should perform the following sanity checks.

Note: In order to perform all of the sanity checks, you will need BOTH your NST development system and a running NST probe.

== Commit ==

You should do a commit to ensure that you do not have any outstanding modifications.

svn commit

== Build Yum Repository ==

Run the following from the top level directory to make certain that you can build and update all the RPM files that make up the NST repository.

sudo dnf clean all
make repo-build

== Check Enabled Services ==

Make sure you boot a recent ISO image and verify that the expected services are enabled at boot time. Be aware that the '''sshd''' and '''httpd''' services will not be enabled or running until the '''nstpasswd''' command is run.

[root@localhost ~]# chkconfig --list | grep 3:on

Note: This output shows SysV services only and does not include native
systemd services. SysV configuration data might be overridden by native
systemd configuration.

If you want to list systemd services use 'systemctl list-unit-files'.
To see services enabled on particular target use
'systemctl list-dependencies [target]'.

livesys 0:off 1:off 2:off 3:on 4:on 5:on 6:off
livesys-late 0:off 1:off 2:off 3:on 4:on 5:on 6:off
[root@localhost ~]#

As noted in the output, the above doesn't show information about native systemd services. To view those services as well, run the following command and review the output produced. NOTE: The output shown below was produced after booting the NST ISO in VirtualBox and selecting the ''Console'' target and running ''nstpasswd''.

[root@probe ~]# systemctl list-unit-files | grep "enabled " | grep service | sort
abrt-journal-core.service enabled enabled
abrt-oops.service enabled enabled
abrt-vmcore.service enabled enabled
abrt-xorg.service enabled enabled
accounts-daemon.service enabled enabled
dbus-daemon.service enabled enabled
dkms.service enabled enabled
getty@.service enabled enabled
import-state.service enabled enabled
irqbalance.service enabled enabled
lightdm.service enabled enabled
lvm2-monitor.service enabled enabled
mcelog.service enabled enabled
ModemManager.service enabled enabled
NetworkManager-dispatcher.service enabled enabled
NetworkManager.service enabled enabled
NetworkManager-wait-online.service enabled enabled
nstboot.service enabled enabled
nstwui.service enabled disabled
ostree-remount.service enabled enabled
pmcd.service enabled enabled
pmie.service enabled enabled
pmlogger.service enabled enabled
rsyslog.service enabled enabled
rtkit-daemon.service enabled enabled
selinux-autorelabel-mark.service enabled enabled
smartd.service enabled enabled
sshd.service enabled disabled
sssd.service enabled enabled
switcheroo-control.service enabled enabled
systemd-homed-activate.service enabled disabled
systemd-homed.service enabled enabled
systemd-network-generator.service enabled enabled
systemd-pstore.service enabled enabled
udisks2.service enabled enabled
upower.service enabled enabled
vboxservice.service enabled enabled
vgauthd.service enabled disabled
vmtoolsd.service enabled enabled
[root@probe ~]#

You might only see the ''vboxservice.service'' entry if you are running under VirtualBox.

== Verify That Documentation Builds ==

Make sure the ''docs'' directory builds. This is required to update the on-line version of the man pages for the release:

[root@dev repo]# cd docs
[root@dev docs]# make

== Run Automated Tests ==

Run the following from the top level to perform numerous checks on the running NST probe with the IP address specified.

make probe-check HOST=IP

There will be a LOT of output produced. A copy of the output will be saved to the file: "probe-check.log" which may be viewed using the command: "less -R probe-check.log". Make sure the file looks clean (or like you would expect). Make sure you aren't tempted to skip this step. We thought we were OK and skipped this step during the 1.8.1 release and ended up delivering a ISO image with a broken sym-link.

NST Avahi (mDNS) FAQ

2023-02-12T23:27:16Z

Paul Blankenbaker:

__TOC__
= Avahi/mDNS General =

== What Services Need to Be Running? ==

The ''avahi-daemon.service'' needs to be running. You can check its status via:

systemctl status avahi-daemon.service

You can start it via:

sudo systemctl start avahi-daemon.service

You can enable it so it is started at boot time via:

sudo systemctl enable avahi-daemon.service

== How Do I enable the resolving of Avahi (mDNS) addresses when using systemd-resolved? ==

The systemd-resolved service can be used to handle the "resolve" entry in /etc/nsswitch.conf (this is typically just before dns is invoked).

hosts: files myhostname mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns

If you choose to enabled systemd-resolved, you can leave /etc/nsswitch.conf alone. However, if you'd like to reduce it, you can simplify the hosts entry to:

hosts: myhostname resolve

To enable and start the systemd-resolved service:

sudo systemctl enable --now systemd-resolved

The default configuration for systemd-resolved has the MulticastDNS option disabled. So, you won't be able to resolve Avahi (mDNS) entries by default. To enable, uncomment or add the following line to /etc/systemd/resolved.conf:

MulticastDNS=yes

Then restart the systemd-resolved service:

sudo systemctl restart systemd-resolved

Finally, you can use the systemd-resolve command to configure how systemd-resolved should resolve mDNS addresses, in particular what interfaces it should resolve (resolvectl can probably be used as well):

sudo systemd-resolve --set-mdns=yes --interface=enp0s3

You can then use the systemd-resolve or getent hosts command to check that addresses can be resolved to host names and that host names can be resolved to addresses. Verify DNS, file and mDNS entries:

systemd-resolve localhost
systemd-resolve nas.local
systemd-resolve 192.168.1.201
systemd-resolve www.google.com
getent hosts www.cnn.com

You can also use PHP or Python to make sure that the gethostbyname and gethostbyaddr functions are also able to resolve names and addresses. Here is a PHP example:

echo "<?php echo(gethostbyname('www.google.com')) ?>" | php
echo "<?php echo(gethostbyname('pollomocha.local')) ?>" | php
echo "<?php echo(gethostbyaddr('192.168.1.201')) ?>" | php

NOTE: In my configuration, the gethostbyname for .local names seems to work much faster for C/PHP/Python that makes use of the glibc gethostbyname function. The "getent hosts NAME.local" command also works, but appears to be very slow in comparison when mDNS resolving is enabled.

== How Do I enable the resolving of Avahi (mDNS) addresses when not using systemd-resolved? ==

The systemd-resolved service can be used to handle the "resolve" entry in /etc/nsswitch.conf (this is typically just before dns is invoked).

hosts: files myhostname mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns

To be able to fully resolve MutlicastDNS names to IPv4 addresses (and vice versa), you can change the hosts line to the following to get the fully functional mDNS resolver that allows you to resolve names to addresses and vice versa:

hosts: files myhostname mdns4 [NOTFOUND=return] dns

Since resolve was removed, you can also disable the systemd-resolved service:

sudo systemctl disable --now systemd-resolved

You can then use the getent command to check that addresses can be resolved to host names and that host names can be resolved to addresses. Verify DNS, file and mDNS entries:

getent hosts localhost
getent hosts nas.local
getent hosts 192.168.1.201
getent hosts www.google.com

You can also use PHP or Python to make sure that the gethostbyname and gethostbyaddr functions are also able to resolve names and addresses. Here is a PHP example:

echo "<?php echo(gethostbyname('www.google.com')) ?>" | php
echo "<?php echo(gethostbyname('pollomocha.local')) ?>" | php
echo "<?php echo(gethostbyaddr('192.168.1.201')) ?>" | php

NOTE: Changing from mdns4_minimal to mdns4 in /etc/nsswitch.conf may come with a performance cost, see https://github.com/lathiat/nss-mdns.

== How Do I Resolve Using Avahi (mDNS) by hand? ==

You can use the ''avahi-resolve'' command to verify that a host name resolves to an IPv4 or IPv6 address.

[root@nst-test ~]# avahi-resolve -4 -n nst-test.local
nst-test.local 192.168.1.221
[root@nst-test ~]# avahi-resolve -6 -n nst-test.local
nst-test.local 2600:1700:1850:e820:56a0:f48:d01f:86bd
[root@nst-test ~]#

== How Do I Add Avahi Resolving to nsswitch.conf? ==

You need to have the following packages installed:

sudo dnf install avahi-daemon nss-mdns

You need to have the ''avahi-daemon'' service running:

sudo systemctl start avahi-daemon.service
sudo systemctl enable avahi-daemon.service

In order for normal commands (like ''ping'', ''ssh'', etc) to resolve Avahi host names, you need to have the following configuration line in your ''/etc/nsswitch.conf'' file:

hosts: files mdns4_minimal [NOTFOUND=return] dns myhostname

This line is typically added automatically when you add the nss-mdns package.

== What Happens If My Router Resolves .local Domains? ==

I have run into AT&T WIFI access points that resolve .local domains under the normal DNS protocol. This breaks normal Avahi lookups and was driving me crazy for several weeks. I finally came across an answer to this issue at [https://bugzilla.redhat.com/show_bug.cgi?id=1690078 Red Hat Bugzilla – Bug 1690078]. Basically on an NST system, you need to:

* Change the ''/etc/nsswitch.conf'' file to use the ''mdns4'' library instead of the ''mdns4_minimal'' library:

# Work around to dang AT&T Access Point resolving .local domains
hosts: files mdns4 [NOTFOUND=return] dns myhostname

* Create a /etc/mdns.allow file with the following entries:

# Work around to dang AT&T Access Point resolving .local domains
.local.
.local

== How Do I Scan My Network For Avahi Service? ==

The easy was is to use the NST Web Interface. From the menu bar, select ''Security'' -> ''Active Scanners'' -> ''NST Avahi (mDNS) Discovery''. This will generate a table of available services and hosts with active links that allow further inspection.

Alternatively, you can run the following from the command line:

sudo avahi-browse --all

NST Avahi (mDNS) FAQ

2023-02-12T23:11:12Z

Paul Blankenbaker:

__TOC__
= Avahi/mDNS General =

== What Services Need to Be Running? ==

The ''avahi-daemon.service'' needs to be running. You can check its status via:

systemctl status avahi-daemon.service

You can start it via:

sudo systemctl start avahi-daemon.service

You can enable it so it is started at boot time via:

sudo systemctl enable avahi-daemon.service

== How Do I Resolve Avahi (mDNS) addresses when using systemd-resolved? ==

The systemd-resolved service can be used to handle the "resolve" entry in /etc/nsswitch.conf (this is typically just before dns is invoked).

hosts: files myhostname mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns

If you choose to enabled systemd-resolved, you can leave /etc/nsswitch.conf alone. However, if you'd like to reduce it, you can simplify the hosts entry to:

hosts: myhostname resolve

To enable and start the systemd-resolved service:

sudo systemctl enable --now systemd-resolved

The default configuration for systemd-resolved has the MulticastDNS option disabled. So, you won't be able to resolve Avahi (mDNS) entries by default. To enable, uncomment or add the following line to /etc/systemd/resolved.conf:

MulticastDNS=yes

Then restart the systemd-resolved service:

sudo systemctl restart systemd-resolved

Finally, you can use the systemd-resolve command to configure how systemd-resolved should resolve mDNS addresses, in particular what interfaces it should resolve (resolvectl can probably be used as well):

sudo systemd-resolve --set-mdns=yes --interface=enp0s3

You can then use the systemd-resolve command to check that addresses can be resolved to host names and that host names can be resolved to addresses. Verify DNS, file and mDNS entries:

systemctl-resolve localhost
systemctl-resolve nas.local
systemctl-resolve 192.168.1.201
systemctl-resolve www.google.com

You can also use PHP or Python to make sure that the gethostbyname and gethostbyaddr functions are also able to resolve names and addresses. Here is a PHP example:

echo "<?php echo(gethostbyname('www.google.com')) ?>" | php
echo "<?php echo(gethostbyname('pollomocha.local')) ?>" | php
echo "<?php echo(gethostbyaddr('192.168.1.201')) ?>" | php

NOTE: In my configuration, the gethostbyname for .local names seems to work much faster for C/PHP/Python that makes use of the glibc gethostbyname function. The "getent hosts NAME.local" command also works, but appears to be very slow in comparison when mDNS resolving is enabled.

== How Do I Resolve Using Avahi (mDNS)? ==

You can use the ''avahi-resolve'' command to verify that a host name resolves to an IPv4 or IPv6 address.

[root@nst-test ~]# avahi-resolve -4 -n nst-test.local
nst-test.local 192.168.1.221
[root@nst-test ~]# avahi-resolve -6 -n nst-test.local
nst-test.local 2600:1700:1850:e820:56a0:f48:d01f:86bd
[root@nst-test ~]#

== How Do I Add Avahi Resolving to nsswitch.conf? ==

You need to have the following packages installed:

sudo dnf install avahi-daemon nss-mdns

You need to have the ''avahi-daemon'' service running:

sudo systemctl start avahi-daemon.service
sudo systemctl enable avahi-daemon.service

In order for normal commands (like ''ping'', ''ssh'', etc) to resolve Avahi host names, you need to have the following configuration line in your ''/etc/nsswitch.conf'' file:

hosts: files mdns4_minimal [NOTFOUND=return] dns myhostname

This line is typically added automatically when you add the nss-mdns package.

== What Happens If My Router Resolves .local Domains? ==

I have run into AT&T WIFI access points that resolve .local domains under the normal DNS protocol. This breaks normal Avahi lookups and was driving me crazy for several weeks. I finally came across an answer to this issue at [https://bugzilla.redhat.com/show_bug.cgi?id=1690078 Red Hat Bugzilla – Bug 1690078]. Basically on an NST system, you need to:

* Change the ''/etc/nsswitch.conf'' file to use the ''mdns4'' library instead of the ''mdns4_minimal'' library:

# Work around to dang AT&T Access Point resolving .local domains
hosts: files mdns4 [NOTFOUND=return] dns myhostname

* Create a /etc/mdns.allow file with the following entries:

# Work around to dang AT&T Access Point resolving .local domains
.local.
.local

== How Do I Scan My Network For Avahi Service? ==

The easy was is to use the NST Web Interface. From the menu bar, select ''Security'' -> ''Active Scanners'' -> ''NST Avahi (mDNS) Discovery''. This will generate a table of available services and hosts with active links that allow further inspection.

Alternatively, you can run the following from the command line:

sudo avahi-browse --all

NST Avahi (mDNS) FAQ

2023-02-12T21:43:38Z

Paul Blankenbaker: Added section on how to configure systemd-resolved to handle mDNS addresses

__TOC__
= Avahi/mDNS General =

== What Services Need to Be Running? ==

The ''avahi-daemon.service'' needs to be running. You can check its status via:

systemctl status avahi-daemon.service

You can start it via:

sudo systemctl start avahi-daemon.service

You can enable it so it is started at boot time via:

sudo systemctl enable avahi-daemon.service

== How Do I Resolve Avahi (mDNS) addresses when using systemd-resolved? ==

The systemd-resolved service can be used to handle the "resolve" entry in /etc/nsswitch.conf (this is typically just before dns is invoked).

hosts: files myhostname mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns

If you choose to enabled systemd-resolved, you can leave /etc/nsswitch.conf alone. However, if you'd like to reduce it, you can simplify the hosts entry to:

hosts: myhostname resolve

To enable and start the systemd-resolved service:

sudo systemctl enable --now systemd-resolved

The default configuration for systemd-resolved has the MulticastDNS option disabled. So, you won't be able to resolve Avahi (mDNS) entries by default. To enable, uncomment or add the following line to /etc/systemd/resolved.conf:

MulticastDNS=yes

Then restart the systemd-resolved service:

sudo systemctl restart systemd-resolved

Finally, you can use the systemd-resolve command to configure how systemd-resolved should resolve mDNS addresses, in particular what interfaces it should resolve (resolvectl can probably be used as well):

sudo systemd-resolve --set-mdns=yes --interface=enp0s3

You can then use the systemd-resolve command to check that addresses can be resolved to host names and that host names can be resolved to addresses. Verify DNS, file and mDNS entries:

systemctl-resolve localhost
systemctl-resolve nas.local
systemctl-resolve 192.168.1.201
systemctl-resolve www.google.com

You can also use PHP or Python to make sure that the gethostbyname and gethostbyaddr functions are also able to resolve names and addresses. Here is a PHP example:

echo "<?php echo(gethostbyname('www.google.com')) ?>" | php
echo "<?php echo(gethostbyname('pollomocha.local')) ?>" | php
echo "<?php echo(gethostbyaddr('192.168.1.201')) ?>" | php

== How Do I Resolve Using Avahi (mDNS)? ==

You can use the ''avahi-resolve'' command to verify that a host name resolves to an IPv4 or IPv6 address.

[root@nst-test ~]# avahi-resolve -4 -n nst-test.local
nst-test.local 192.168.1.221
[root@nst-test ~]# avahi-resolve -6 -n nst-test.local
nst-test.local 2600:1700:1850:e820:56a0:f48:d01f:86bd
[root@nst-test ~]#

== How Do I Add Avahi Resolving to nsswitch.conf? ==

You need to have the following packages installed:

sudo dnf install avahi-daemon nss-mdns

You need to have the ''avahi-daemon'' service running:

sudo systemctl start avahi-daemon.service
sudo systemctl enable avahi-daemon.service

In order for normal commands (like ''ping'', ''ssh'', etc) to resolve Avahi host names, you need to have the following configuration line in your ''/etc/nsswitch.conf'' file:

hosts: files mdns4_minimal [NOTFOUND=return] dns myhostname

This line is typically added automatically when you add the nss-mdns package.

== What Happens If My Router Resolves .local Domains? ==

I have run into AT&T WIFI access points that resolve .local domains under the normal DNS protocol. This breaks normal Avahi lookups and was driving me crazy for several weeks. I finally came across an answer to this issue at [https://bugzilla.redhat.com/show_bug.cgi?id=1690078 Red Hat Bugzilla – Bug 1690078]. Basically on an NST system, you need to:

* Change the ''/etc/nsswitch.conf'' file to use the ''mdns4'' library instead of the ''mdns4_minimal'' library:

# Work around to dang AT&T Access Point resolving .local domains
hosts: files mdns4 [NOTFOUND=return] dns myhostname

* Create a /etc/mdns.allow file with the following entries:

# Work around to dang AT&T Access Point resolving .local domains
.local.
.local

== How Do I Scan My Network For Avahi Service? ==

The easy was is to use the NST Web Interface. From the menu bar, select ''Security'' -> ''Active Scanners'' -> ''NST Avahi (mDNS) Discovery''. This will generate a table of available services and hosts with active links that allow further inspection.

Alternatively, you can run the following from the command line:

sudo avahi-browse --all

Final Merge From Development Area

2022-07-10T15:39:59Z

Paul Blankenbaker: Updated for 36

Before building a release, make sure that all of the updates to your development area have committed and merged into the ''repo''.

To verify that your ''dev'' area is up to date and committed:

[nst@nst-repo dev]$ svn update
Updating '.':
At revision 11990.
[nst@nst-repo dev]$ svn commit
[nst@nst-repo dev]$ svn status -u
Status against revision: 11990
[nst@nst-repo dev]$

If you have not created the ''repo'' area yet for release, do so now with an ''svn cp'' command similar to the following (replace USERID with your SourceForge login):

USERID=YOUR_USERID
svn cp svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/dev/36 svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/repo/36

Use the ''svn info'' command to verify that the ''Last Changed Rev'' value in the ''repo'' area is greater than or equal to the value in the ''dev'' area.

[nst@nst-repo dev]$ svn info https://svn.code.sf.net/p/nst/code/dev/36
Path: 36
URL: https://svn.code.sf.net/p/nst/code/dev/36
Relative URL: ^/dev/36
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 11991
Node Kind: directory
Last Changed Author: pblankenbaker
Last Changed Rev: 11990
Last Changed Date: 2020-06-07 07:23:17 -0400 (Sun, 07 Jun 2020)

[nst@nst36-repo livecd]$ svn info https://svn.code.sf.net/p/nst/code/repo/36
Path: 36
URL: https://svn.code.sf.net/p/nst/code/repo/36
Relative URL: ^/repo/36
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 11991
Node Kind: directory
Last Changed Author: pblankenbaker
Last Changed Rev: 11991
Last Changed Date: 2020-06-07 07:29:36 -0400 (Sun, 07 Jun 2020)

[nst@nst-repo dev]$

In the output above, we see that the ''dev'' area is at revision ''11991'' as is the ''repo''. Had the ''repo'' area been at revision lower than ''11991'', a merge will be required. To perform the merge, follow the instructions found on the [[Subversion Notes]] page.

Do a Sanity Check

2022-07-10T15:31:29Z

Paul Blankenbaker: Updated systemctl expected output

Prior to creating a release, one should perform the following sanity checks.

Note: In order to perform all of the sanity checks, you will need BOTH your NST development system and a running NST probe.

== Commit ==

You should do a commit to ensure that you do not have any outstanding modifications.

svn commit

== Build Yum Repository ==

Run the following from the top level directory to make certain that you can build and update all the RPM files that make up the NST repository.

sudo dnf clean all
make repo-build

== Check Enabled Services ==

Make sure you boot a recent ISO image and verify that the expected services are enabled at boot time. Be aware that the '''sshd''' and '''httpd''' services will not be enabled or running until the '''nstpasswd''' command is run.

[root@localhost ~]# chkconfig --list | grep 3:on

Note: This output shows SysV services only and does not include native
systemd services. SysV configuration data might be overridden by native
systemd configuration.

If you want to list systemd services use 'systemctl list-unit-files'.
To see services enabled on particular target use
'systemctl list-dependencies [target]'.

livesys 0:off 1:off 2:off 3:on 4:on 5:on 6:off
livesys-late 0:off 1:off 2:off 3:on 4:on 5:on 6:off
[root@localhost ~]#

As noted in the output, the above doesn't show information about native systemd services. To view those services as well, run the following command and review the output produced. NOTE: The output shown below was produced after booting the NST ISO in VirtualBox and selecting the ''Console'' target and running ''nstpasswd''.

[root@probe ~]# systemctl list-unit-files | grep "enabled " | grep service | sort
abrt-journal-core.service enabled enabled
abrt-oops.service enabled enabled
abrt-vmcore.service enabled enabled
abrt-xorg.service enabled enabled
accounts-daemon.service enabled enabled
dbus-daemon.service enabled enabled
dkms.service enabled enabled
getty@.service enabled enabled
import-state.service enabled enabled
irqbalance.service enabled enabled
lightdm.service enabled enabled
lvm2-monitor.service enabled enabled
mcelog.service enabled enabled
ModemManager.service enabled enabled
NetworkManager-dispatcher.service enabled enabled
NetworkManager.service enabled enabled
NetworkManager-wait-online.service enabled enabled
nstboot.service enabled enabled
nstwui.service enabled disabled
ostree-remount.service enabled enabled
pmcd.service enabled enabled
pmie.service enabled enabled
pmlogger.service enabled enabled
rsyslog.service enabled enabled
rtkit-daemon.service enabled enabled
selinux-autorelabel-mark.service enabled enabled
smartd.service enabled enabled
sshd.service enabled disabled
sssd.service enabled enabled
systemd-boot-update.service enabled enabled
systemd-network-generator.service enabled enabled
udisks2.service enabled enabled
upower.service enabled enabled
vboxservice.service enabled enabled
vgauthd.service enabled disabled
vmtoolsd.service enabled enabled
[root@probe ~]#

You might only see the ''vboxservice.service'' entry if you are running under VirtualBox.

== Verify That Documentation Builds ==

Make sure the ''docs'' directory builds. This is required to update the on-line version of the man pages for the release:

[root@dev repo]# cd docs
[root@dev docs]# make

== Run Automated Tests ==

Run the following from the top level to perform numerous checks on the running NST probe with the IP address specified.

make probe-check HOST=IP

There will be a LOT of output produced. A copy of the output will be saved to the file: "probe-check.log" which may be viewed using the command: "less -R probe-check.log". Make sure the file looks clean (or like you would expect). Make sure you aren't tempted to skip this step. We thought we were OK and skipped this step during the 1.8.1 release and ended up delivering a ISO image with a broken sym-link.

Console Output and Serial Terminals

2021-07-04T16:54:06Z

Paul Blankenbaker: /* Serial Console: Oracle VirtualBox */

__TOC__
= '''Overview''' =
This page describes different methods for setting up a serial console post booting up an NST system. See '''[[Getting Started#Server_.28Serial_Console.29 | Getting Started - Server Boot]]''' for setting up a serial console initially during a NST Live boot.

= '''Serial Devices''' =

== '''Enabling More Than 4 Serial Devices''' ==

By default, the Linux kernel that comes with Fedora (and hence the NST) enables 4 serial devices (''/dev/ttyS0'', ''/dev/ttyS1'', ''/dev/ttyS2'' and ''/dev/ttyS3''). If your hardware has more than 4 total serial devices, you will want to add the "''8250.nr_uarts=COUNT''" parameter to your boot options in ''/boot/grub/grub.conf''.

For example, a system with one serial port on the motherboard and eight serial ports on a SeaLevel PCI adapter would have a total of nine serial ports available. In order to get access to all of the available serial ports on this system, the following parameter was added to the kernel parameters line in ''/boot/grub/grub.conf'':

8250.nr_uarts=9

== '''Determine Availability and Mapping''' ==

The ''/proc/tty/driver/serial'' file can be invaluable when trying to determine which physical serial port maps to which device entry. For example, on a system with one serial port on the motherboard and eight serial ports on a SeaLevel PCI adapter, ''/proc//tty/driver/serial'' reported the following:

<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>cat /proc/tty/driver/serial</div>
<pre class="computerOutput">
serinfo:1.0 driver revision:
0: uart:16550A port:000003F8 irq:4 tx:0 rx:0
1: uart:16550A port:0000C828 irq:16 tx:226 rx:42 brk:1 RTS|CTS|DTR|DSR
2: uart:16550A port:0000C830 irq:16 tx:31 rx:0 RTS|DTR
3: uart:16550A port:0000C838 irq:16 tx:24 rx:0
4: uart:16550A port:0000C800 irq:16 tx:24 rx:0
5: uart:16550A port:0000C808 irq:16 tx:24 rx:0
6: uart:16550A port:0000C810 irq:16 tx:24 rx:0
7: uart:16550A port:0000C818 irq:16 tx:24 rx:0
8: uart:16550A port:0000C820 irq:16 tx:1718 rx:0 RTS|DTR
[root@probe ~]#
</pre>
</div>

The above output provides clues that ''/dev/ttyS0'' mapped to the serial port on the motherboard (which is what you would expect). However, the other port addresses indicated that the eight serial ports on the SeaLevel PCI adapter did ''not'' map out as you would expect. The first physical port on the SeaLevel PCI adapter mapped to ''/dev/ttyS4''. The clue here was that ports on the SeaLevel adapter started at port 0xC800 (as shown by the '''lspci''' output below). Why the sixth port on the PCI adapter (at port 0xC828) mapped to ''/dev/ttyS1'' is a mystery, but at least the output above helped to sort out the mapping.

<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>lspci -v</div>
<pre class="computerOutput">

01:05.0 Serial controller: Sealevel Systems Inc Eight Port RS-232 Interface (rev 01) (prog-if 02 [16550])
Subsystem: Sealevel Systems Inc Eight Port RS-232 Interface
Flags: medium devsel, IRQ 16
Memory at effff000 (32-bit, non-prefetchable) [size=128]
I/O ports at cc00 [size=128]
I/O ports at c800 [size=64]
Kernel driver in use: serial

[root@probe ~]#
</pre>
</div>

= '''Serial Terminal On NST 2.13.0''' =
== Add Serial Console On Device: /dev/ttyS0 ==
Use the following command to manually enable the serial console on NST versions 2.13.0 using '''[http://upstart.ubuntu.com/ upstart]'''. This example will set the serial baud rate to: "'''57600'''" and use serial device: "'''/dev/ttyS0'''".
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>initctl emit --no-wait fedora.serial-console-available ttyS0 57600</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>
A user login prompt should now be active on serial device: "'''/dev/ttyS0'''".

= '''Serial Terminal On NST 2.15.0 or Above''' =

== Add A Serial Terminal On Device: /dev/ttyS0 ==

[[Image:Warning.png‎]] See the topic: "'''[[Bash_Advanced_Topics#systemctl_Bash_Completion |Enabling systemctl Bash Completion]]'''" for making it quick and easy to complete the '''systemctl''' command.

Use the following command to manually enable a serial terminal on NST versions 2.15.x or above using '''[http://www.freedesktop.org/wiki/Software/systemd systemd]'''. This example will use the current baud rate ('''[http://en.wikipedia.org/wiki/Getty_%28Unix%29 agetty] -s''' option) set typically during a boot time and use serial device: "'''/dev/ttyS0'''". If one needs to adjust the baud rate, send a ''break'' character on your communications application to cycle through the baud rate list (i.e., In this example: 115200, 38400 and 9600).
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl start serial-getty@ttyS0.service</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>
A user login prompt should now be active on serial device: "'''/dev/ttyS0'''". To get status use the '''systemctl''' command as follows:
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl status serial-getty@ttyS0.service</div>
<pre class="computerOutput">
serial-getty@ttyS0.service - Serial Getty on ttyS0
Loaded: loaded (/lib/systemd/system/serial-getty@.service)
Active: active (running) since Tue, 17 May 2011 16:59:56 -0400; 5min ago
Main PID: 31524 (agetty)
CGroup: name=systemd:/system/serial-getty@.service/ttyS0
└ 31524 /sbin/agetty -s ttyS0 115200 38400 9600
[root@probe ~]#
</pre>
</div>

== Add An Additional Serial Login Device: '''/dev/ttyUSB0''' ==
One can add an additional '''Serial''' user login session on a serial device. If your NST system does not have a physical serial port, you can plugin a '''USB To Serial Converter''' device for user login. In this example we are adding a '''USB To Serial Converter''' which attaches as device: "'''ttyUSB0'''". Simply start a serial login on this device as follows:
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl start serial-getty@ttyUSB0.service</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>
A user login prompt should now be active on serial device: "'''/dev/ttyUSB0'''". To status for this device use the '''systemctl''' command as follows:
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl status serial-getty@ttyUSB0.service</div>
<pre class="computerOutput">
serial-getty@ttyUSB0.service - Serial Getty on ttyUSB0
Loaded: loaded (/lib/systemd/system/serial-getty@.service)
Active: active (running) since Fri, 20 May 2011 21:13:55 -0400; 3min 24s ago
Main PID: 1273 (agetty)
CGroup: name=systemd:/system/serial-getty@.service/ttyUSB0
└ 1273 /sbin/agetty -s ttyUSB0 115200 38400 9600
[root@probe ~]#
</pre>
</div>

To make this configuration permanent add the following:
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>ln -sf /lib/systemd/system/getty@.service /etc/systemd/system/getty.target.wants/getty@ttyUSB0.service</div>
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl daemon-reload</div>
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl start getty@ttyUSB0.service</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>

== Steps To Add A Custom Serial Login Device: "/dev/ttyS1" ==
Use the following procedure to add a custom serial login device under '''systemd''' control. In this example we will add the ability for user login on the second serial device: "'''/dev/ttyS1'''" using a fixed baud rate of 57600 and 8-bits clean with no flow control.

<div class="centerBlock"><div class="noteMessage">'''Note:''' This has been changed to 115200 baud since the NST 28 Interim release.</div></div>

'''1.''' Get a copy of "/lib/systemd/system/serial-getty@.service" and place it in directory: "/etc/systemd/system" and give it a custom name (e.g., "serial-getty-fterm@.service").
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>cp /lib/systemd/system/serial-getty\@.service /etc/systemd/system/serial-getty-fterm\@.service</div>
<div class="userInput"><span class="prompt">[root@probe ~]# </span>ls -al /etc/systemd/system</div>
<pre class="computerOutput">
total 32
drwxr-xr-x. 7 root root 4096 May 22 20:30 .
drwxr-xr-x. 4 root root 4096 May 15 19:22 ..
lrwxrwxrwx 1 root root 36 May 16 09:26 default.target -> /lib/systemd/system/runlevel5.target
drwxr-xr-x. 2 root root 4096 May 15 19:13 default.target.wants
drwxr-xr-x. 2 root root 4096 May 22 20:26 getty.target.wants
drwxr-xr-x. 2 root root 4096 May 15 19:26 graphical.target.wants
drwxr-xr-x. 2 root root 4096 May 16 09:26 multi-user.target.wants
-rw-r--r-- 1 root root 903 May 22 16:36 serial-getty-fterm@.service
drwxr-xr-x. 2 root root 4096 May 15 19:13 sysinit.target.wants
[root@probe ~]#
</pre>
</div>

'''2.''' Edit custom file (Using 57600 baud): "/etc/systemd/system/serial-getty-fterm@.service" and set the fixed baud rate of 57600 on the "'''ExecStart'''" line.
<pre class="programListing">
# This file is part of systemd.
#
# systemd is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.

[Unit]
Description=Serial Getty on %I
BindTo=dev-%i.device
After=dev-%i.device systemd-user-sessions.service plymouth-quit-wait.service
After=rc-local.service

# If additional gettys are spawned during boot then we should make
# sure that this is synchronized before getty.target, even though
# getty.target didn't actually pull it in.
Before=getty.target

[Service]
Environment=TERM=vt100
ExecStart=-/sbin/agetty %I 57600
Restart=always
RestartSec=0
UtmpIdentifier=%I
KillMode=process

# Some login implementations ignore SIGTERM, so we send SIGHUP
# instead, to ensure that login terminates cleanly.
KillSignal=SIGHUP
</pre>

'''2.''' Edit custom file (Using 115200 baud): "/etc/systemd/system/serial-getty-fterm@.service" and set the fixed baud rate of 115200 on the "'''ExecStart'''" line.
<pre class="programListing">
# This file is part of systemd.
#
# systemd is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.

[Unit]
Description=Serial Getty on %I
BindTo=dev-%i.device
After=dev-%i.device systemd-user-sessions.service plymouth-quit-wait.service
After=rc-local.service

# If additional gettys are spawned during boot then we should make
# sure that this is synchronized before getty.target, even though
# getty.target didn't actually pull it in.
Before=getty.target

[Service]
Environment=TERM=vt100
ExecStart=-/sbin/agetty %I 115200
Restart=always
RestartSec=0
UtmpIdentifier=%I
KillMode=process

# Some login implementations ignore SIGTERM, so we send SIGHUP
# instead, to ensure that login terminates cleanly.
KillSignal=SIGHUP
</pre>

'''3.''' Create a symbolic link in directory: "/etc/systemd/system" using serial device: "'''/dev/ttyS1'''" to custom file: "/etc/systemd/system/serial-getty-fterm@.service". This will make the configuration permanent across reboots.
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>ln -s /etc/systemd/system/serial-getty-fterm\@.service /etc/systemd/system/getty.target.wants/serial-getty-fterm@ttyS1.service</div>
<div class="userInput"><span class="prompt">[root@probe ~]# </span>ls -al /etc/systemd/system/getty.target.wants</div>
<pre class="computerOutput">
drwxr-xr-x. 2 root root 4096 May 22 20:26 .
drwxr-xr-x. 7 root root 4096 May 22 20:25 ..
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty1.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty2.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty3.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty4.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty5.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx. 1 root root 34 May 15 19:13 getty@tty6.service -> /lib/systemd/system/getty@.service
lrwxrwxrwx 1 root root 47 May 22 20:26 serial-getty-fterm@ttyS1.service -> /etc/systemd/system/serial-getty-fterm@.service
lrwxrwxrwx 1 root root 41 May 20 21:12 serial-getty@ttyUSB0.service -> /lib/systemd/system/serial-getty@.service
[root@probe ~]#
</pre>
</div>

'''4.''' Manually control '''systemd''' using '''systemctl''' to startup the login service via '''[http://en.wikipedia.org/wiki/Getty_%28Unix%29 agetty]''' on device: "'''/dev/ttyS1'''". '''systemd''' will do this automatically during the boot process.
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl start serial-getty-fterm@ttyS1.service</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>

'''5.''' Check the current service status for serial login on device: "'''/dev/ttyS1'''"
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl status serial-getty@ttyS1.service</div>
<pre class="computerOutput">
serial-getty@ttyS1.service - Serial Getty on ttyS1
Loaded: loaded (/etc/systemd/system/serial-getty-fterm@.service)
Active: active (running) since Sun, 22 May 2011 20:09:39 -0400; 8s ago
Main PID: 6408 (agetty)
CGroup: name=systemd:/system/serial-getty-fterm@.service/ttyS1
└ 6408 /sbin/agetty ttyS1 57600
[root@probe ~]#
</pre>
</div>

== The ModemManager May Interfere With A USB Serial Port Adapter ==
[[Image:Warning.png‎]] The '''[http://projects.gnome.org/NetworkManager/ NetworkManager]''' application uses the '''[http://cgit.freedesktop.org/ModemManager/ModemManager/ ModemManager]''' plugin. If you have NetworkManager running and are using the '''[http://en.wikipedia.org/wiki/Minicom minicom]''' terminal emulation program with a USB serial port adapter, then you may experience garbage characters being sent to the USB serial port. These characters are generated from the ModemManager application and may prove to be undesirable. One solution to resolve this issue is to disable the startup of the ModemManager application via the NetworkManager. This can be accomplished with the following:

<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>mv /usr/share/dbus-1/system-services/org.freedesktop.ModemManager.service \</div>
<div class="userInput">/usr/share/dbus-1/system-services/org.freedesktop.ModemManager.service.disable</div>
<pre class="computerOutput">
[root@probe ~]#
</pre>
</div>

Now reboot your NST system:
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>systemctl reboot</div>
</div>

 

= Serial Console In Virtual Environments =

== Serial Console: VMware Workstation (Linux) ==
This section will describe the steps needed to attach a serial device to an NST Virtual Machine (VM) under VMware Workstation (v7.1.x or greater) control for serial console output. This will allow one to examine the complete boot sequence via the serial console output including boot strapping the Linux Kernel. See the article: '''[http://www.linuxsmiths.com/blog/?p=312 Using the VMware Workstation emulated serial port on a Linux host]''' for advanced usage (i.e., Howto setup a Linux Kernel serial debugger) of the serial console under VMware Workstation control. In this example we will add a '''Unix Socket''' connection serial type and use the '''[http://en.wikipedia.org/wiki/Netcat nc]''' (netcat) utility for attachment to the socket ('''I/O''') in a Gnome Terminal. Alternatively, one could use the '''[http://en.wikipedia.org/wiki/Minicom minicom]''' terminal emulation program and set the serial device to point to a Unix socket (e.g., "'''unix#/tmp/nstcom2'''").

'''1.''' To add a serial port to an '''NST VM''', using the following menu sequence on VMware Workstation: '''VM''' => '''Settings''' => '''Add''' => '''Serial Port''' => '''Next''' => '''Output to socket'''. In this example we are adding the Device: "'''Serial Port 2'''" (Linux serial device: /dev/ttyS1) with Unix socket name: "'''/tmp/nstcom2'''". See the screenshots below:

[[Image:Vmwarews_serial_socket_add.png|center|frame|Adding A Serial Device Under VMware Workstation]]

The serial port setting for VMware Workstation after adding the Device: "'''Serial Port 2'''" with Unix socket name: "'''/tmp/nstcom2'''" will be shown as:

[[Image:Vmwarews_serial_socket_setup.png|center|frame|VMware Workstation - Device: Serial Port 2 with Unix Socket: "/tmp/nstcom2"]]

'''2.''' The Unix socket: "'''/tmp/nstcom2'''" will <u>not</u> be ''created'' until the VM is started by VMware Workstation. Therefore, in order to see the entire serial console output, start the VM with "'''Power On to BIOS'''" (Menu Sequence: '''VM''' => '''Power''' => '''Power On to BIOS'''). Once in the '''BIOS''', the socket will be created.

'''3.''' Now on your Linux host system, startup a Gnome Terminal. Make sure you edit the "'''Profile Preferences'''" set the '''Scrollback''' to "'''unlimited'''" to capture all serial console output.

'''4.''' Start the '''nc''' utility to use: "'''UNIX-domain sockets'''" and attach it to the socket created by VMware Workstation (i.e. nc -U /tmp/nstcom2).

[[Image:Gnome_terminal_nc_socket.png|center|frame|Start the 'nc' utility in a Gnome Terminal with Attached Unix Socket (Serial Console: ttyS1)]]

'''5.''' Now back on the NST VM, exit from the BIOS setup menu to either the NST Live '''[http://en.wikipedia.org/wiki/Syslinux SYSLINUX]''' menu or the NST '''[http://en.wikipedia.org/wiki/GNU_GRUB GNU GRUB]''' boot menu. Select a boot choice and add the kernel parameter: "'''console=ttyS1'''" to it. Use the '''<tab>''' key for editing an NST Live menu boot choice or use the ''''e'''' key to edit an NST GNU GRUB choice. Below is a screenshot for editing the NST Live boot choice: "'''NST v2.15.0 - Console'''".

[[Image:Nst_live_boot_add_serial_console.png|center|frame|Add Serial Console: ttyS1 to NST Live Boot Choice: 'NST v2.15.0 - Console']]

'''6.''' Now continue booting your NST VM and serial output should be directed to the Gnome Terminal. Since this is a serial console one can also log into NST after the VM has booted.

[[Image:Gnome_terminal_nc_socket_output.png|center|frame|Gnome Terminal: Serial Console Output - Device: "/dev/ttyS1"]]

'''7.''' One can list the attached serial console devices using the following.
<div class="screen">
<div class="userInput"><span class="prompt">[root@probe ~]# </span>cat /proc/consoles</div>
<pre class="computerOutput">
ttyS1 -W- (EC p a) 4:65
[root@probe ~]#
</pre>
</div>

== Serial Console: VMware Workstation (Windows) ==
This section will describe the steps needed to attach a serial device to an NST Virtual Machine (VM) under VMware Workstation (v15.5.x or greater) control for serial console output. We will use the '''[https://en.wikipedia.org/wiki/PuTTY Putty]''' application with a '''[https://en.wikipedia.org/wiki/Named_pipe Named Pipe]''' connection type.

* Added a Serial Port to the NST VM and configure with a named pipe connection type using the Windows named pipe naming convention: "'''\\.\pipe\<Unique Pipe Name>'''"

[[Image:Vmware_workstation_settings_serial.png|center|frame|Configuring A Serial Adapter Under VMware Workstation]]

<div class="centerBlock"><div class="noteMessage">'''Note:''' Use the following command in a Microsoft Windows PowerShell terminal: "'''[System.IO.Directory]::GetFiles("\\.\pipe\")'''" to show all current named pipes:
PS C:\Users\User> [System.IO.Directory]::GetFiles("\\.\pipe\")
\\.\pipe\InitShutdown
.
.
.
\\.\pipe\nst32_console
</div></div>

* Next configure a Putty serial session with the corresponding named pipe connection type named used above (i.e., "'''\\.\pipe\nst32_console'''"). Typically the serial baud rate should be set to: "'''115200'''".

[[Image:Putty_session_serial.png|center|frame|Configuring A Serial Session using a Named Pipe with Putty]]

* Next configure serial options in the NST Grub2 file: "'''/etc/nst/grub2/nst_grub2_defaults'''" to allow for a Grub2 Serial Console and Server Login Console using "'''agetty'''".

Example: Serial options section to enable a Grub2 Serial Console (*Note: --unit is set to "'''1'''" - The virtual serial port added by VMware Workstation):

<pre class="programListing">
.
.
.
# Uncomment For A NST Grub Serial Console
# --------- --- - --- ---- ------ -------
GRUB_SERIAL_COMMAND="serial --unit=1 --speed=115200 --word=8 --parity=no --stop=1";
GRUB_TERMINAL_INPUT="serial console";
GRUB_TERMINAL_OUTPUT="serial console";
.
.
.
</pre>

Example: Serial options section to enable a Server Login Console Boot entry (*Note: NST_SERIAL_DEV[idx] is set to "'''/dev/ttyS1'''" - The virtual serial port added by VMware Workstation):

<pre class="programListing">
.
.
.
#
# NST Server Console Boot
# --- ------ ------- ----
NST_SERIAL[idx]="true";
NST_SERIAL_DEV[idx]="ttyS1";
NST_SERIAL_BAUD[idx]="115200";
NST_TITLE[idx]="Server (Serial ${NST_SERIAL_DEV[idx]} at ${NST_SERIAL_BAUD[idx]})";
NST_GRUB_CMDLINE_LINUX[idx]="audit=0 systemd.unit=multi-user.target";
NST_GRUB_SAVEDEFAULT[idx]="true";
NST_GRAPHICAL_BOOT[idx]="false";
idx=idx+1;
.
.
.
</pre>

* Finally rebuild the NST Grub2 boot entries using "'''nstboot'''" and then reboot. Open up your Putty session for the serial console session.
[root@NST32 ~]# nstboot -v --grub2;
+ BEGIN + Rebuilding the 'Grub2' configuration file: "/boot/grub2/grub.cfg"

Check/Adding NST Boot Grub2 Defaults file: "/etc/nst/grub2/nst_grub2_defaults"
===============================================================================
Already included...

Generating the NST Grub2 Configuration file: "/boot/grub2/grub.cfg"
===============================================================================
/sbin/grub2-mkconfig --output="/boot/grub2/grub.cfg";
Generating grub configuration file ...
[15133.188809] JFS: nTxBlock = 8192, nTxLock = 65536
[15133.280272] raid6: skip pq benchmark and using algorithm avx2x4
[15133.283570] raid6: using avx2x2 recovery algorithm
[15133.298083] xor: automatically using best checksumming function avx
[15133.402637] Btrfs loaded, crc32c=crc32c-intel
Found linux image: /boot/vmlinuz-5.6.18-300.fc32.x86_64
Found initrd image: /boot/initramfs-5.6.18-300.fc32.x86_64.img
done

+ END + Successfully ran the 'Grub2' configuration rebuild
[root@NST32 ~]#
[root@NST32 ~]# systemctl reboot;

== Serial Console: Oracle VirtualBox ==

This section will describe the steps needed to attach a serial device to an NST Virtual Machine (VM) under Oracle VirtualBox (v4.0.8) control for serial console output. This will allow one to examine the complete boot sequence via the serial console output including boot strapping the Linux Kernel. In this example we will:

* Enable a virtual serial port.
* Set the virtual serial port mode to ''Host Pipe''.
* Use the '''[http://en.wikipedia.org/wiki/Netcat nc]''' (netcat) utility running in a Gnome Terminal to monitor ''virtual serial output'' from the NST booted within VirtualBox.

To add a serial port to an '''NST VM''' in VirtualBox:

* Select your virtual machine and then click on the ''Settings'' icon.
* From the settings panel, select ''Serial Ports'' on the left side and then select the ''Port 1'' tab.
* Fill in the ''Port 1'' settings as shown in the screen shot below:

[[Image:VirtualBox6_serial_port_settings.png|center|frame|Configuring A Serial Port Under Oracle VirtualBox 6]]

Newer versions of VirtualBox will create the named pipe by default. If you have an older version of VirtualBox, you may need to select the checkbox labeled "Create Pipe":

[[Image:VirtualBox_serial_port_settings.png|center|frame|Configuring A Serial Port Under Oracle VirtualBox]]

The Unix pipe: "'''/tmp/nst-ttyS0.pipe'''" will be created when the virtual machine is started (not before). So, the trick to capture everything is to be ready to start the '''nc''' command in a '''gnome-terminal''' when the virtual machine goes through its initial BIOS routines.

* Open a '''gnome-terminal'''.
* Type in the following command, but ''do not hit Enter'' - just get the command ready to run.
nc -U /tmp/nst-ttyS0.pipe
* Power on your virtual machine and as soon as you see the BIOS screen, press the Enter key in your '''gnome-terminal''' to start the '''nc''' command.
* Click back on the virtual machine window and use the down arrow key to select the ''Server'' boot mode.
* If things go according to plan, your two windows should resemble the following:

[[Image:VirtualBox_nst_boot.png|center|frame|Selecting Server mode in VirtualBox]]

[[Image:Gnome_terminal_nc_socket_vbox1.png|center|frame|Serial output from syslinux captured using nc to grab VirtualBox virtual serial output]]

At this point, you can press the Enter key in the VirtualBox window to start the boot process. You should see the entire boot log appear in your '''gnome-terminal''' where the '''nc''' command is running.

= Grabbing the Console With an '''xterm''' =

To grab console output using an '''xterm''', start up an '''xterm''' terminal with the ''-C'' option:

xterm -C &

NOTE: This appears to grab all console output (any other devices you originally had configured to capture console output may no longer do so).

= Logging in as the 'root' User on a Specific Device =
In order to login as user: ''''root'''' on a specific device, make sure that the device is listed in the "'''/etc/securetty'''" file. The "'''/etc/securetty'''" file is read by the login program: "'''/bin/login'''". Its format is a list of the tty devices names allowed, and for all others that are commented out or do not appear in this file, ''''root'''' login is disallowed. For example, to login as user: ''''root'''' on USB serial device: "'''ttyUSB0'''" make sure it is added to the "'''/etc/securetty'''" file. See the example content below for file: "'''/etc/securetty'''":

<pre class="programListing">
console
vc/1
vc/2
vc/3
vc/4
vc/5
vc/6
vc/7
vc/8
vc/9
vc/10
vc/11
tty1
tty2
tty3
tty4
tty5
tty6
tty7
tty8
tty9
tty10
tty11
ttyUSB0
</pre>

= Minicom Setup for NST Serial Console Login =

== Overview ==
This setup uses a USB Prolific Technology, Inc. PL2303 Serial Port Adapter attached as device: "'''/dev/ttyUSB0'''".

== Known To Work USB to TTL Serial Adapter Converter ==
This USB to TTL Serial Adapter is known to work with NST: '''[https://www.makerfocus.com/products/2pcs-usb-to-ttl-serial-adapter-converter-compatible-with-windows-7-8-10-wince-linux-mac USB Serial Adapter]''' which uses the '''[http://www.ftdichip.com/Support/Documents/DataSheets/ICs/DS_FT232R.pdf FTDI IC device FT232R]''' chip set.

[[File:FT232RL.jpg|256x256px|frameless|FT232RL USB Serial Adapter]]

== Minicom Configuration File ==
[root@dell1564 ~]# cat /etc/minirc.ttyUSB0;
#
# NST Serial Login Console
pu port /dev/ttyUSB0
pu baudrate 115200
pu bits 8
pu parity N
pu stopbits 1
pu rtscts No
pu xonxoff No
#
# Disable modem initialization values...
pu minit
pu mreset
pu mdialpre
pu mdialsuf
pu mdialpre2
pu mdialsuf2
pu mdialpre3
pu mdialsuf3
pu mhangup
pu mdialcan
[root@dell1564 ~]#

== Minicom Command Line ==
[root@dell1564 ~]# minicom -w -c on -t xterm ttyUSB0;

== Exit Minicom Session ==
To exit a minicom session use key sequence: '''Ctrl-A, Z, q'''

File:VirtualBox6 serial port settings.png

2021-07-04T16:52:21Z

Paul Blankenbaker: VirtualBox 6 creates named pipe by default

== Summary ==
VirtualBox 6 creates named pipe by default

Update/Add Manifest and Release Links

2021-06-17T04:02:04Z

Paul Blankenbaker:

As we've created a new release, you should review links that are release and manifest related. Within the HTML documentation, you can locate the release related links by examining:

* The NST related links at the top of the links page (update file: ''html/links.html'').

* The rules to generate the HTML version of the manifest (update file: ''html/include/make/makefile'').

* Bump the release number for the nstweb package (update file: ''yum/pkgs/nstweb/pkginfo.xml'').

* Add a '''%changelog''' entry (update file: ''yum/pkgs/nstweb/template.spec'').

* Finally, update the ''NST Feature Release'' information section in the file: ''html/welcome.html'' with the following:
** Verify/Update the release date
** Verify any Kernel version information.
** Update the hard link to the final manifest.
** Update the timeout (for when the ''NST Feature Release'' information section is not longer automatically shown, allow for roughly two months).

Do a Sanity Check

2021-06-13T17:52:53Z

Paul Blankenbaker:

Prior to creating a release, one should perform the following sanity checks.

Note: In order to perform all of the sanity checks, you will need BOTH your NST development system and a running NST probe.

== Commit ==

You should do a commit to ensure that you do not have any outstanding modifications.

svn commit

== Build Yum Repository ==

Run the following from the top level directory to make certain that you can build and update all the RPM files that make up the NST repository.

sudo dnf clean all
make repo-build

== Check Enabled Services ==

Make sure you boot a recent ISO image and verify that the expected services are enabled at boot time. Be aware that the '''sshd''' and '''httpd''' services will not be enabled or running until the '''nstpasswd''' command is run.

[root@localhost ~]# chkconfig --list | grep 3:on

Note: This output shows SysV services only and does not include native
systemd services. SysV configuration data might be overridden by native
systemd configuration.

If you want to list systemd services use 'systemctl list-unit-files'.
To see services enabled on particular target use
'systemctl list-dependencies [target]'.

livesys 0:off 1:off 2:off 3:on 4:on 5:on 6:off
livesys-late 0:off 1:off 2:off 3:on 4:on 5:on 6:off
[root@localhost ~]#

As noted in the output, the above doesn't show information about native systemd services. To view those services as well, run the following command and review the output produced. NOTE: The output shown below was produced after booting the NST ISO in VirtualBox and selecting the ''Console'' target and running ''nstpasswd''.

[root@probe ~]# systemctl list-unit-files | grep "enabled " | grep service | sort
#UNIT FILE STATE VENDOR PRESET
abrt-journal-core.service enabled enabled
abrt-oops.service enabled enabled
abrt-vmcore.service enabled enabled
abrt-xorg.service enabled enabled
accounts-daemon.service enabled enabled
dbus-daemon.service enabled enabled
dkms.service enabled enabled
getty@.service enabled enabled
import-state.service enabled enabled
irqbalance.service enabled enabled
lightdm.service enabled enabled
lvm2-monitor.service enabled enabled
mcelog.service enabled enabled
ModemManager.service enabled enabled
multipathd.service enabled enabled
NetworkManager-dispatcher.service enabled enabled
NetworkManager.service enabled enabled
NetworkManager-wait-online.service enabled enabled
nstboot.service enabled enabled
nstwui.service enabled disabled
ostree-remount.service enabled enabled
pmcd.service enabled enabled
pmie.service enabled enabled
pmlogger.service enabled enabled
rsyslog.service enabled enabled
rtkit-daemon.service enabled enabled
selinux-autorelabel-mark.service enabled enabled
smartd.service enabled enabled
sshd.service enabled disabled
sssd.service enabled enabled
systemd-homed-activate.service enabled disabled
systemd-homed.service enabled enabled
udisks2.service enabled enabled
upower.service enabled enabled
vboxservice.service enabled enabled
vgauthd.service enabled disabled
vmtoolsd.service enabled enabled
[root@probe ~]#

You might only see the ''vboxservice.service'' entry if you are running under VirtualBox.

== Verify That Documentation Builds ==

Make sure the ''docs'' directory builds. This is required to update the on-line version of the man pages for the release:

[root@dev repo]# cd docs
[root@dev docs]# make

== Run Automated Tests ==

Run the following from the top level to perform numerous checks on the running NST probe with the IP address specified.

make probe-check HOST=IP

There will be a LOT of output produced. A copy of the output will be saved to the file: "probe-check.log" which may be viewed using the command: "less -R probe-check.log". Make sure the file looks clean (or like you would expect). Make sure you aren't tempted to skip this step. We thought we were OK and skipped this step during the 1.8.1 release and ended up delivering a ISO image with a broken sym-link.

Manual Package Updates

2021-06-13T17:05:08Z

Paul Blankenbaker:

Currently, there are no packages which have "add-ons" which need to be manually updated.

* Update the IAB and OUI files used by the arp-scan utility (use NST WUI to get two new ones download then transfer to ''src'' directory for the ''arp-scan'' RPM).

= Check Package URLs =

There are many ''pkginfo.xml'' files which are associated with the RPM packages making up the NST yum repository. Each of these ''pkginfo.xml'' files will have two or more URLs. As time goes by these URLs may ''move'' and need to be updated. You can run the ''make url-check'' command from the ''yum'' directory to:

* Extract the URLs from each fo the ''pkginfo.xml'' files.
* Run the ''curl -head'' command on each of the extracted URLs.
* See '''ok''', '''skip''' or '''FAIL''' displayed on the screen next to each URL as it is checked.
* Create two log files: ''url-check.log'' and ''url-check-details.log''.

Here is a example of running the command:

[root@taco-dev32 dev]# cd yum
[root@taco-dev32 yum]# make url-check
[ok] file:///root/dev/yum/pkgs/ipsc/src/ipsc-0.4.3.tar.bz2
[ok] file:///root/dev/yum/pkgs/nst-disk-speed/src/seeker.c
[ok] file:///root/dev/yum/pkgs/smtpclient/src/smtpclient-1.0.0.tar.gz
[ok] file:///root/dev/yum/pkgs/tcptrack/src/tcptrack-1.4.2.tar.gz

... output continues as all URLs are checked ...

[root@taco-dev32 yum]#

If you just want to see the list of URLs with issues, you can run the following '''grep''' command on the generated log file:

[root@taco-dev32 yum]# grep -v ok url-check.log
[skip] git://github.com/gnumaniacs/netsniff-ng.git
[root@taco-dev32 yum]#

NOTE: The ''skip'' entries indicate protocols which '''curl''' is unable to handle and verification is skipped. If you would like to verify the skipped entries, you will need to do it manually.

= Check Date Change Logs =

Run the following command to verify that all change log dates in the spec files are good.

[nst28-repo@nst yum]$ make changelog-date-check
all - Changelog date(s) ok
[nst28-repo@nst yum]$

Make Sure Public Repos Are Setup

2021-06-13T15:20:14Z

Paul Blankenbaker: Updated for NST 34 links

You should verify that the public mirror list and ''yum'' repositories have be set up.

* Check the public repository mirror listing(s) for the release: http://www.networksecuritytoolkit.org/nst/mirrors/repo-f34-x86_64.mirrors.txt
* If you don't see a text mirror list file for the 64 bit release you need to do the following:
** Create and add the missing files to ''html/mirrors'' on the development machine.
** Edit the ''yum/pkgs/nstweb/pkginfo.xml'' file and bump the release number and update the dependency list for the new mirror files added.
** Push out the mirrors and initial empty ''yum'' repositories by running the following commands on the development machine:
[root@dev repo]# cd ~/nstpro
[root@dev nstpro]# make upload-repo
* Verify that you can load the empty repomd.xml file from each of the listed mirrors for the release. For example:
** http://networksecuritytoolkit.org/repo/nst/f34/x86_64/repodata/repomd.xml

'''NOTE''': If there are any errors, you may need to log into the mirrors to create the top level directories.

'''NOTE''': You skip this step for interim releases.

'''NOTE''': To create an ''empty'' repository at networksecuritytoolkit.org, log into the web server and run the following commands:
cd ~/public_html/repo/nst
install -d f34 && ln -s ../empty f34/x86_64

Build and Update the Yum Repository

2020-06-07T12:17:48Z

Paul Blankenbaker:

Before building the ISO release image, you should make sure the NST yum repository is up to date and built for a ISO release.

You can also prime the pump by copying your development cache area to your new repository build area. This is optional, but saves download time and avoids the case of a server being down or an author upgrading a package since your last testing cycle.

The following will prune any old package builds and delta RPMs out of your repository and make sure the configuration files in the ''nst-release'' package are updated (these are the files that end up under the ''/etc/nst/iso/'' directory). This can be done using the following command:

[nst@nst-repo repo]$ svn update # To make sure you are in sync with your manifest commit
[nst@nst-repo repo]$ cp -r ../dev/yum/cache yum/
[nst@nst-repo repo]$ make release-repo-build

Final Merge From Development Area

2020-06-07T11:36:46Z

Paul Blankenbaker:

Before building a release, make sure that all of the updates to your development area have committed and merged into the ''repo''.

To verify that your ''dev'' area is up to date and committed:

[nst@nst-repo dev]$ svn update
Updating '.':
At revision 11990.
[nst@nst-repo dev]$ svn commit
[nst@nst-repo dev]$ svn status -u
Status against revision: 11990
[nst@nst-repo dev]$

If you have not created the ''repo'' area yet for release, do so now with an ''svn cp'' command similar to the following (replace USERID with your SourceForge login):

USERID=YOUR_USERID
svn cp svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/dev/32 svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/repo/32

Use the ''svn info'' command to verify that the ''Last Changed Rev'' value in the ''repo'' area is greater than or equal to the value in the ''dev'' area.

[nst@nst-repo dev]$ svn info https://svn.code.sf.net/p/nst/code/dev/32
Path: 32
URL: https://svn.code.sf.net/p/nst/code/dev/32
Relative URL: ^/dev/32
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 11991
Node Kind: directory
Last Changed Author: pblankenbaker
Last Changed Rev: 11990
Last Changed Date: 2020-06-07 07:23:17 -0400 (Sun, 07 Jun 2020)

[nst@nst32-repo livecd]$ svn info https://svn.code.sf.net/p/nst/code/repo/32
Path: 32
URL: https://svn.code.sf.net/p/nst/code/repo/32
Relative URL: ^/repo/32
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 11991
Node Kind: directory
Last Changed Author: pblankenbaker
Last Changed Rev: 11991
Last Changed Date: 2020-06-07 07:29:36 -0400 (Sun, 07 Jun 2020)

[nst@nst-repo dev]$

In the output above, we see that the ''dev'' area is at revision ''11991'' as is the ''repo''. Had the ''repo'' area been at revision lower than ''11991'', a merge will be required. To perform the merge, follow the instructions found on the [[Subversion Notes]] page.

Final Merge From Development Area

2020-06-07T11:33:35Z

Paul Blankenbaker: Updated for NST 32 release

Before building a release, make sure that all of the updates to your development area have committed and merged into the ''repo''.

To verify that your ''dev'' area is up to date and committed:

[nst@nst-repo dev]$ svn update
Updating '.':
At revision 11990.
[nst@nst-repo dev]$ svn commit
[nst@nst-repo dev]$ svn status -u
Status against revision: 11990
[nst@nst-repo dev]$

If you have not created the ''repo'' area yet for release, do so now with an ''svn cp'' command similar to the following (replace USERID with your SourceForge login):

USERID=YOUR_USERID
svn cp svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/dev/32 svn+ssh://${USERID}@svn.code.sf.net/p/nst/code/repo/32

Use the ''svn info'' command to verify that the ''Last Changed Rev'' value in the ''repo'' area is greater than or equal to the value in the ''dev'' area.

[nst@nst-repo dev]$ svn info https://svn.code.sf.net/p/nst/code/dev/32
Path: 32
URL: https://svn.code.sf.net/p/nst/code/dev/32
Relative URL: ^/dev/32
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 11991
Node Kind: directory
Last Changed Author: pblankenbaker
Last Changed Rev: 11990
Last Changed Date: 2020-06-07 07:23:17 -0400 (Sun, 07 Jun 2020)

[nst@nst-repo dev]$

In the output above, we see that the ''dev'' area is at revision ''11991'' as is the ''repo''. Had the ''repo'' area been at revision lower than ''11991'', a merge will be required. To perform the merge, follow the instructions found on the [[Subversion Notes]] page.

NST and Virtual Machines

2020-01-22T19:25:28Z

Paul Blankenbaker: Added section on creating VMDK meta file

__TOC__
= General Virtual Machine Questions =

== What Virtual Machines Will NST Run Under? ==

NST is currently known to run under:

* The '''[http://www.vmware.com/products/ VMware Product]''' line.
* '''[http://www.virtualbox.org/ VirtualBox]'''

== What are the Disadvantages of Running NST within a Virtual Machine? ==

* Performance will be less than running NST on bare metal system (i.e., Running natively).
* Wireless tools will not work as physical wireless adapters appear are typically virtualized as Ethernet NICs.

== What are the Advantages of Running NST within a Virtual Machine? ==

* You can monitor the traffic on the virtual machine network switches without any cables or hardware.
* You can easily move your NST system to a different machine.

== Can I Run Virtual Machines from a NST System? ==

Yes. If you perform a full installation of NST, you can install a virtual environment and run virtual machines within your NST system. For example, if you install VirtualBox onto your NST system, it will be possible to run Operating Systems like "'''Windows 7'''" virtually within your NST system.

Both the VMware and VirtualBox environments are known to run on a NST system. Any virtual environment which runs under Fedora should work on a NST system as well.

= VirtualBox Frequently Asked Questions =



== Why can't I monitor all traffic on the virtual network adapter? ==

There are two likely reasons that can trigger this issue:

1. The network adapter must be up and enabled on the host system before a virtualized NST system will be able to see any traffic on the adapter. If this is the issue, you will need to enable the network adapter on the machine which hosts the virtual NST (outside of the NST system).

2. VirtualBox allows one to specify the "virtual hardware implementation" when configuring network adapters. We have seen the case where some "virtual hardware implementations" do not properly support promiscuous mode operation within the NST environment (in particular some of the ''E1000'' adapters).

So, if you run across this condition, we recommend that you try a different "virtual hardware implementation" (the ''PCnet Fast-III'' implementation has worked for us).

== How do I install the VirtualBox Guest Additions? ==

* Install the following packages that are necessary to build the kernel modules:

yum install gcc kernel-devel

* From the ''Devices'' menu of VirtualBox, click on the ''Install Guest Additions'' options. If things go well, a virtual CD will appear on your GNOME desktop.

* Open a terminal window and login as ''root'' (if you aren't already logged in as root).

* Copy the contents of the CD to a temporary directory, run the installation script, and then remove the temporary directory (NOTE: While ''VBOX*'' will probably work as shown below, it is recommended to replace it with the actual directory name):

cp -rp /media/VBOX* /tmp/
cd /tmp/VBOX*
./VBoxLinuxAdditions-x86.run # NOTE: Run ./VBoxLinuxAdditions-amd64.run if 64 bit machine
cd
rm -fr /tmp/VBOX*

* Reboot the system (may not always be required - you can't do this step if running from a Live boot).

== How do I update the VirtualBox Guest Additions? ==

Anytime you update the kernel on a NST system running under VirtualBox, you will need to rebuild the VirtualBox kernel module. This can be done using the following command:

service vboxadd setup

It's recommended to either reboot your machine or restart the VirtualBox services after rebuilding the kernel module. Here are the commands to restart the VirtualBox services:

service vboxadd restart
service vboxadd-x11 restart
service vboxadd-service restart

NOTE: You may or may not have the ''vboxadd-x11'' service.

NOTE: Updating and restarting the services won't necessarily fix your current X session. So, if you are logged into a graphical desktop, you will need to log out and back in order to make use of the VirtualBox drivers.

== How do I install VirtualBox Server onto a NST Distribution? ==

See the [[HowTo Install VirtualBox]] page for details.

== How do I update the VirtualBox Server Modules on the Host Hypervisor (v3.1.x)? ==

Anytime you update the kernel on a Linux based system running VirtualBox v3.1.x, you will need to tell VirtualBox to rebuild its kernel modules. This can be done using the following command:

service vboxdrv setup;

NOTE: This this is different than the "VirtualBox Guest Additions" as this refers to the native OS under which the VirtualBox environment is running under.

== How do I update the VirtualBox Server Modules on the Host Hypervisor (v5.0.x)? ==

Anytime you update the kernel on a Linux based system running VirtualBox v5.0.x, you will need to tell VirtualBox to rebuild its kernel modules. This can be done using the following command:

/sbin/rcvboxdrv setup;

NOTE: This this is different than the "VirtualBox Guest Additions" as this refers to the native OS under which the VirtualBox environment is running under.

== USB Access: VirtualBox 6.x or Greater ==
VMs running on VirtualBox 6.x or greater requires the user running the VirtualBox hypervisor to be added to the "'''vboxusers'''" group. In this example we will add the "'''nst'''" user to the "'''vboxusers'''" group.

usermod -G vboxusers -a nst;

= VMware Frequently Asked Questions =

== Why Would I Want To Run NST Under VMware? ==

There are several reasons why one may want to boot the Network Security Toolkit from within a VMware virtual machine:

* You would like to have a full hard disk installation of the Network Security Toolkit, but don't want to re-partition your hard disk.
* You would simply like to try out a new Network Security Toolkit ISO distribution, but don't want to reboot your system. Using the free [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/player/ VMware Player], one can boot the Network Security Toolkit directly from the ISO file (you won't need to burn a disk).
* You'd like to monitor the network traffic to and from a particular Windows machine, and you don't have the necessary hardware to tap into what's going across the Ethernet cable. By booting the Network Security Toolkit within a virtual machine on the Windows machine, you will be able to monitor the Ethernet traffic with tools such as wireshark, snort, ntop, etc.
* You are doing development on a Windows machine and would like to use some of the features from the Network Security Toolkit without using an additional machine (the Network Security Toolkit makes it pretty easy to setup a web server or SQL database in these situations).

== How Do I Convert A Raw Disk Image To VMDK ==

It is fairly easy to make raw disk images using the dd command on a block device. While VirtualBox provides a fairly straight forward way to make use of raw disk images, VMware does not. You need to create a "meta" VMDK file to go with your disk image and upload both the raw disk image file into your virtual environment. For example, let's assume that you want to make a raw disk image of the USB drive that appears as /dev/sdb. You could run the following command:

sudo dd status=progress if=/dev/sdb bs=$((1024 * 1024 * 4)) of=usb.img

Now that you have your raw disk image (''usb.img''), you need to create a corresponding VMDK file describing the disk image. You can use the following bash script to accomplish this (copy the following to a file called ''create-vmdk.bash'').

<syntaxhighlight lang="sh">#!/bin/bash

declare fileName="${1}";
declare -i fileSize=${2:-$(stat --printf="%s" "$fileName" 2>/dev/null)};

if [ "${fileSize}" == "" ] || ((fileSize <= 0)); then
echo -e "
Usage: create-vmdk.bash FILE_NAME [FILE_SIZE]

Where: FILE_NAME - Name of raw disk image file
FILE_SIZE - Size of image in bytes
"
exit 1;
fi

# Helper method to generate VMDK descriptor for raw image
# a raw disk image. See following URL with info about
# VMDK files for raw disk images:
#
# https://communities.vmware.com/thread/533089

createVmdk() {
declare file="${1}";
declare -i sizeBytes=${2};
declare -i sizeSectors=$((sizeBytes / 512));
declare -i sizeCylinders=$((sizeSectors / 16065));
declare cid="12345678";
declare bn="$(basename "${file}")";

echo -e "# Disk DescriptorFile
version=1
encoding=\"UTF-8\"
CID=${cid}
parentCID=ffffffff
createType=\"vmfs\"
# Extent description
RW ${sizeSectors} VMFS \"${bn}\"
# The Disk Data Base
#DDB
ddb.virtualHWVersion = \"8\"
ddb.geometry.cylinders = \"${sizeCylinders}\"
ddb.geometry.heads = \"255\"
ddb.geometry.sectors = \"63\"
ddb.adapterType = \"lsilogic\"";
}

createVmdk "${fileName}" ${fileSize};
</syntaxhighlight>

You can then invoke the script as follows to create ''usb.img.vmdk''.

./create-vmdk.bash usb.img >| usb.img.vmdk

Next, upload both the ''usb.img'' and ''usb.img.vmdk'' files to your VMware environment. If things work as they have in the past, you should have a new disk image available for use within your VMware environment that can be attached and detached to virtual machines as needed.

== How Much Does It Cost? ==

While some of the [http://www.vmware.com/ VMware virtualization] products do cost money, others like [http://www.vmware.com/products/server/ VMware Server] and [http://www.vmware.com/products/player/ VMware Player] do not. The choice is yours as NST should run within all of VMware's virtual environments.

== What Version(s) of the NST Work Within VMware Virtualization Environments? ==

The '''1.4.1''' and later releases of the Network Security Toolkit should work very well as a guest OS within a VMware virtual environment. These newer releases of the Network Security Toolkit will include the [http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware] script and the [http://open-vm-tools.sourceforge.net/ open-vm-tools] package to maximize the performance of the Network Security Toolkit when running from within a Virtual machine.

== Are the VMware Tools & Modules Included? ==

Yes, starting with the '''1.4.1''' release of the Network Security Toolkit we have included the various kernel modules and utility programs necessary for optimal performance within a VMware virtual environment.

Starting with the '''2.11.0''' release of the NST package, these tools are found in the [http://open-vm-tools.sourceforge.net/ open-vm-tools] package.

== Is There a Pre-Built VMware NST Virtual Machine Available? ==

Yes. You should be able to find a pre-built version of the NST Virtual Machine on the [http://sourceforge.net/project/showfiles.php?group_id=85467 project's download page]. These downloads will be large ZIP files with a naming convention of: "''nst-vm-VERSION.ARCH.zip''" where ''VERSION'' corresponds to the NST release and ''ARCH'' corresponds to the hardware archecture. For example: ''nst-vm-2.13.0.i686.zip''.

The '''2.13.0''' release of the NST was the first time that both a 32 bit (i686) and 64 bit (x86_64) pre-built NST virtual machine was made available for direct download.

== How Do I Use the NST ISO in a VMware Virtual Machine? ==

If you've already downloaded the NST ISO image(s), you don't need to download the large pre-built NST virtual machine ZIP file(s). You can build your own NST virtual machine fairly simply using an NST ISO image.

In order to boot the Network Security Toolkit ISO image from within a VMware virtual machine, we recommend that you follow these steps:

* Install [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/player/ VMware Player] onto your host system.
* Next download and unzip the "''nst-vm-live-VERSION.ARCH.zip''" file onto your host system. When this file is unzipped it will create a "nst-VERSION-ARCH" directory containing the necessary files to boot the Network Security Toolkit ISO image.
* Next, if necessary, download a ISO image of the Network Security Toolkit from NST [http://sourceforge.net/project/showfiles.php?group_id=85467 project's download page]. You can also download the ISO image directly from a running Network Security Toolkit system using the "''Get CD/DVD/Device Image''" page in the NST WUI (select ''System'' then ''File System Management'' from the main menu bar to find the link to the page).
* Copy (or move) the ISO image into the "''nst-VERSION-ARCH''" directory created by the extraction of the "nst-vm-live-VERSION.ARCH.zip" file.
* Start the VMware virtual environment using one of the provided ''.vmx'' files. There are many different VMware virtual environments, here are a couple of examples:
** Under Windows: double clicking on the "''nst-vm-windows-2.11.0.vmx''" icon (you may not see the "''.vmx''" extension).
** Linux users can start the VMware Player on the command line using the following:

[root@striker ~]# vmplayer nst-VERSION-ARCH/nst-vm-linux-VERSION.vmx &

If you intend to use the Network Security Toolkit for a extended period of time, we recommend that you use the ''install mode'' of the [http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware] script to install the distribution to a virtual hard disk. By doing a hard disk install in this manner, your changes will be kept permanently between reboots.

[root@probe ~]# nstvmware -m install -a toolkit -v

... Takes awhile and a lot of output is produced as NST
is installed from the virtual ISO image to the virtual
hard disk image ...

[root@probe ~]# poweroff

... System shuts down and the VMware Player terminates ...

[[File:Warning.png|16px]] Using the "''install''" function of the [http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware] script assumes that a virtual hard disk will be available as ''/dev/sda''. The entire virtual hard disk will be initialized. Any data you may have had on the virtual disk '''will be lost'''! Do not use this command if you have any information on the virtual disk you want to keep.

This will give your toolkit permanent storage and cause it to boot up directly into a graphical desktop login. You may delete or disconnect the ISO image from the virtual machine after installing to the virtual disk. If you do not remove or disconnect the ISO image from the virtual machine, you may need to adjust the "virtual BIOS" settings. To adjust the "virtual BIOS" settings, you'll need to press the "''F2''" key at the appropriate time - watch the boot screen closely.

After a hard disk install, the password will be reset to the factory default value of ''nst2003'' (for NST distributions prior to '''1.4.2''' the default value is ''nst@2003'').

== Are There Limitations To Running NST In A VMware Virtual Environment? ==

There are several limitations that need to be considered when running the Network Security Toolkit under a VMware virtual environment.

* You can not directly access the hard disk of the host system. For example, you will not be able to create/modify the partition table of the host system.
* You can not access files on the host system outside of the virtual machine, unless your VMware environment supports it and you've taken the time to setup the ''shared folders''. You can always use network shared folders and/or '''[http://wiki.linuxquestions.org/wiki/Scp scp]''' commands to transfer files between the host system and the virtual machine.
* Wireless features of the Network Security Toolkit will not be usable within a virtual machine as they tend to require direct access to the wireless adapters. However, you ''might'' be able to get around this limitation if you have a USB WIFI adapter supported by NST. We have not tried experimenting with USB WIFI adapters under VMware, so it might be possible.
* Your privilege level is limited to the user level that started the Network Security Toolkit Virtual Machine. You can not do anything within the Network Security Toolkit Virtual Machine which the user account used on the host machine is not allowed to do. For example, if you are using a "Limited Account" on a Windows XP machine, you will not be able to monitor all of the Ethernet traffic within the Network Security Toolkit Virtual Machine. In this case, the host operating system should limit you to monitoring the traffic which is to/from your virtual system.

== What Does the nstvmware Script Do? ==

The '''[http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware]''' script has several modes of operation and facilitates common tasks that you are likely to perform when booting the Network Security Toolkit within a VMware virtual environment. In particular:

* It allows you to quickly setup a Network Security Toolkit system running within a VMware virtual machine.
* It allows you to easily install the Network Security Toolkit distribution from the booted ISO image onto a virtual disk.
* It allows you to quickly adjust the X settings for different environments. For example, if you have a laptop running at 1600x1200 with a 15.1 inch screen, try running: "''nstvmware -m xorg.conf --width 1600 --height 1200 --diagonal 15.1''", and then restart your X server.
* It allows you to increase the effective font size for the X display. For example, if you have a laptop running at 1600x1200 with a 15.1 inch screen, try running: "''nstvmware -m xorg.conf --width 1600 --height 1200 --diagonal 12''", and then restart your X server. In this case we are faking the screen dimension size smaller which has the effect of increasing the font size for the X display.

For further information on the '''[http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware]''' script, see the '''[http://nst.sourceforge.net/nst/docs/scripts/nstvmware.html nstvmware]''' man page.

== How Do I Add More Than One Network Ethernet Adapter? (VMware Player: Windows) ==

A NST Virtual Machine running under VMware Player host control can utilize multiple network interfaces by running a different network/security application on each one of them.

The following sections cover the details on how to configure additional physical network adapters to be used with a NST Virtual Machine under a Windows-based VMware Player host.

The Windows "''vmx''" VMware Player configuration file: "''nst-vm-windows-VERSION.vmx''" has 4 network Ethernet interfaces already defined. Network interface: "eth0" will start in a "connected" state while network interfaces: "eth1", "eth2" and "eth3" will be started in the disconnected state. Network interface: "eth3" also has its "present" state set to "false". This allows for audio and sound usage with NST. If audio is not required, one can enable the "present" state to "true" for this interface. The connection type (''connectionType'') for each defined network Ethernet interface is set to: "custom".

The following shows the predefined Ethernet interface settings within the Windows "''vmx''" VMware Player configuration file: "''nst-vm-windows-VERSION.vmx''":

ethernet0.present = "TRUE"
ethernet0.virtualDev = "vmxnet"
ethernet0.startConnected = "TRUE"
ethernet0.connectionType = "custom"
ethernet0.vnet = "vmnet0"

ethernet1.present = "TRUE"
ethernet1.virtualDev = "vmxnet"
ethernet1.startConnected = "FALSE"
ethernet1.connectionType = "custom"
ethernet1.vnet = "vmnet2"

ethernet2.present = "TRUE"
ethernet2.virtualDev = "vmxnet"
ethernet2.startConnected = "FALSE"
ethernet2.connectionType = "custom"
ethernet2.vnet = "vmnet3"

ethernet3.present = "FALSE"
ethernet3.virtualDev = "vmxnet"
ethernet3.startConnected = "FALSE"
ethernet3.connectionType = "custom"
ethernet3.vnet = "vmnet4"

'''***Note:''' One can also use the new '''vmxnet3''' virtual network driver. Example for "'''eth0'''":

ethernet0.present = "TRUE"
ethernet0.virtualDev = "vmxnet3"
ethernet0.startConnected = "TRUE"
ethernet0.connectionType = "custom"
ethernet0.vnet = "vmnet0"

According to VMware: The VMXNET 3 adapter is the next generation of a paravirtualized NIC designed for performance, and is not related to VMXNET or VMXNET 2. It offers all the features available in VMXNET 2, and adds several new features like multiqueue support (also known as Receive Side Scaling in Windows), IPv6 offloads, and MSI/MSI-X interrupt delivery.

Each defined network adapter will assume a globally unique "MAC" address when the NST Virtual Machine is first booted up. This allows for multiple NST Virtual Machine instances to exist on the same physical network subnet without duplicate "ARP" entries being discovered.

The following shows an example of the globally unique "MAC" addresses and the "UUID" generated after the first time the NST Virtual Machine is started. This is typically generated at the end of the Windows "''vmx''" VMware Player configuration file: "''nst-vm-windows-VERSION.vmx''".

ethernet0.addressType = "generated"
ethernet1.addressType = "generated"
ethernet2.addressType = "generated"
uuid.location = "56 4d 65 10 d6 b3 92 2d-ac ab 98 13 5e 8d e6 bb"
uuid.bios = "56 4d 65 10 d6 b3 92 2d-ac ab 98 13 5e 8d e6 bb"
ethernet0.generatedAddress = "00:0c:29:8d:e6:bb"
ethernet0.generatedAddressOffset = "0"
ethernet1.generatedAddress = "00:0c:29:8d:e6:c5"
ethernet1.generatedAddressOffset = "10"
ethernet2.generatedAddress = "00:0c:29:8d:e6:cf"
ethernet2.generatedAddressOffset = "20"

A mapping for each physical network adapter to a VMware Player virtual network adapter needs to occur. The Windows "''vmx''" VMware Player configuration file: "''nst-vm-windows-VERSION.vmx''" has already defined the following logical Ethernet to virtual network adapter mapping:

* "eth0" <=> "vmnet0"
* "eth1" <=> "vmnet2"
* "eth2" <=> "vmnet3"
* "eth3" <=> "vmnet4"

Use the '''vmnetcfg.exe''' Windows VMware Player "Virtual Network Editor" found in the top level directory where the VMware Player was installed to perform the physical to virtual network adapter mapping. Each mapping will be associated with a "Bridged" connection type.

Lets use a Windows VMware Player host system configured with 2 physical network ethernet adapters (a "3Com" and a "Xircom CardBus" adapter) to demonstrate a physical to virtual network adapter mapping example:

[[File:Vmnetcfg2.png|center|frame|Physical to Virtual Network Adapter Mapping]]

The logical to virtual to physical network adapter mappings shown above are:

* "eth0" <=> "vmnet0" <=> "3Com 3C920 Integrated Fast Ethernet Adapter"
* "eth1" <=> "vmnet2" <=> "Xircom CardBus Ethernet II 10/100 Adapter"

Once you have completed mapping each network adapter then use the "Virtual Network Editor" Summary tab to review your work:

[[File:Vmnetcfg1.png|center|frame|Virtual Network Adapter Summary Window]]

<div class="wikiNote">'''Note: There is a special usage for virtual network adapter: "vmnet1" and "vmnet8". Adapter: "vmnet1" is used for a "Host-only" connection and adapter: "vmnet8" is used for a "NAT" connection type.</div>

Finally, after the NST Virtual Machine is started you will need to enable the additional network adapter you have just added for this guest virtual machine. It will most likely be in a ''disconnected'' state. Use the VMware Player menu bar to enable the virtual Ethernet device by changing its state to: ''connected''.

== How Do I Add More Than One Network Ethernet Adapter? (VMware Player: Linux) ==

[[File:Warning.png|16px]] This information is outdated and does not pertain to the current NST release!

If your host Linux system is configured with more than one physical network adapter (Wired or Wireless) one can enable up to 4 network ethernet adapters with VMware Player. A NST Virtual Machine running under VMware Player host control can utilize each of the 4 network interfaces by running a different network/security application on each one of them.

The following sections cover the details on how to configure additional physical network adapters to be used with a NST Virtual Machine under a Linux-based VMware Player host.

The preconfigured Linux "vmx" VMware Player configuration file: "nst-vm-linux2.11.0.vmx" has 4 network ethernet interfaces already defined. Network interface: "eth0" will start in a "connected" state while network interfaces: "eth1", "eth2" and "eth3" will be started in the disconnected state. Network interface: "eth3" also has its "present" state set to "false". This allows for audio and sound usage with NST. If audio is not required, one can enable the "present" state to "true" for this interface. The connection type (connectionType) for each defined network ethernet interface is set to: "custom".

The following shows the predefined ethernet interface settings within the Linux "vmx" VMware Player configuration file:

ethernet0.present = "TRUE"
ethernet0.virtualDev = "vmxnet"
ethernet0.startConnected = "TRUE"
ethernet0.connectionType = "custom"
ethernet0.vnet = "/dev/vmnet0"

ethernet1.present = "TRUE"
ethernet1.virtualDev = "vmxnet"
ethernet1.startConnected = "FALSE"
ethernet1.connectionType = "custom"
ethernet1.vnet = "/dev/vmnet2"

ethernet2.present = "TRUE"
ethernet2.virtualDev = "vmxnet"
ethernet2.startConnected = "FALSE"
ethernet2.connectionType = "custom"
ethernet2.vnet = "/dev/vmnet3"

ethernet3.present = "FALSE"
ethernet3.virtualDev = "vmxnet"
ethernet3.startConnected = "FALSE"
ethernet3.connectionType = "custom"
ethernet3.vnet = "/dev/vmnet4"

Each defined network adapter will assume a globally unique "MAC" address when the NST Virtual Machine is first booted up. This allows for multiple NST Virtual Machine instances to exist on the same physical network subnet without duplicate "ARP" entries being discovered.

The following shows an example of the globally unique "MAC" addresses and the "UUID" generated after the first time the NST Virtual Machine is started. This is typically generated at the end of the Linux "vmx" VMware Player configuration file.

ethernet0.addressType = "generated"
ethernet1.addressType = "generated"
ethernet2.addressType = "generated"
uuid.location = "56 4d 21 a4 b2 4c cc ed-2d 17 2d 69 cf d4 fa 6d"
uuid.bios = "56 4d 21 a4 b2 4c cc ed-2d 17 2d 69 cf d4 fa 6d"
ethernet0.generatedAddress = "00:0c:29:d4:fa:6d"
ethernet0.generatedAddressOffset = "0"
ethernet1.generatedAddress = "00:0c:29:d4:fa:77"
ethernet1.generatedAddressOffset = "10"
ethernet2.generatedAddress = "00:0c:29:d4:fa:81"
ethernet2.generatedAddressOffset = "20"

A mapping for each physical network adapter to a VMware Player virtual network adapter needs to occur. The preconfigured Linux "vmx" VMware Player configuration file: "nst-vm-linux2.11.0.vmx" has already defined the following logical ethernet to virtual network adapter mapping:

* "eth0" <=> "/dev/vmnet0"
* "eth1" <=> "/dev/vmnet2"
* "eth2" <=> "/dev/vmnet3"
* "eth3" <=> "/dev/vmnet4"

Use the "/usr/bin/vmware-config.pl" Linux VMware Player "VMware Configurator" script to perform the logical to virtual network adapter mapping. The results of running this script will be to start up a "bridge mapping" process for each network interface that needs to be mapped. Each mapping will be associated with a "Bridged" connection type. After all said and done the physical to logical (done by the Linux Kernel loadable network modules) to virtual network adapter (done by the "/usr/bin/vmware-config.pl" script) mapping will be completed.

Lets use a Linux VMware Player host system configured with 2 physical network ethernet adapters (in this case 2 gigabit ethernet adapters "eth0" and "eth1" adapter) to demostrate a physical to virtual network adapter mapping example:

First lets show what network interfaces are available using the "''/sbin/ifconfig -a''" command:

[root@striker ~]# /sbin/ifconfig -a

eth0 Link encap:Ethernet HWaddr 00:07:E9:0E:2B:7B
inet addr:10.222.222.14 Bcast:10.222.222.255 Mask:255.255.255.0
inet6 addr: fe80::207:e9ff:fe0e:2b7b/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:1075542 errors:0 dropped:0 overruns:0 frame:0
TX packets:910768 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:100
RX bytes:739987052 (705.7 MiB) TX bytes:413469820 (394.3 MiB)
Base address:0xdcc0 Memory:ff6e0000-ff700000

eth1 Link encap:Ethernet HWaddr 00:08:74:4F:EA:35
inet6 addr: fe80::208:74ff:fe4f:ea35/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:1816456 errors:0 dropped:0 overruns:0 frame:0
TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:10
RX bytes:119424833 (113.8 MiB) TX bytes:984 (984.0 b)
Base address:0xdc80 Memory:ff6c0000-ff6e0000

lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:16436 Metric:1
RX packets:3956 errors:0 dropped:0 overruns:0 frame:0
TX packets:3956 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:2504748 (2.3 MiB) TX bytes:2504748 (2.3 MiB)

sit0 Link encap:IPv6-in-IPv4
NOARP MTU:1480 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)

Next we will run the VMware Player "VMware Configurator" script: "/usr/bin/vmware-config.pl" to perform the mapping: (***Note: Only the network mapping output section is shown.)

[root@striker ~]# /usr/bin/vmware-config.pl

...
You have already setup networking.

Would you like to skip networking setup and keep your old settings as they are?
(yes/no) [no]

Do you want networking for your virtual machines? (yes/no/help) [yes]

Would you prefer to modify your existing networking configuration using the
wizard or the editor? (wizard/editor/help) [wizard]

The following bridged networks have been defined:

. vmnet0 is bridged to eth0

Do you wish to configure another bridged network? (yes/no) [no] yes

Configuring a bridged network for vmnet2.

The following bridged networks have been defined:

. vmnet0 is bridged to eth0
. vmnet2 is bridged to eth1

All your ethernet interfaces are already bridged.

Do you want to be able to use NAT networking in your virtual machines? (yes/no)
[yes] no

Do you want to be able to use host-only networking in your virtual machines?
[no]

Extracting the sources of the vmnet module.

Building the vmnet module.

Building for VMware Player 1.0.x or VMware Workstation 5.5.x.
Using 2.6.x kernel build system.
make: Entering directory `/tmp/vmware-config0/vmnet-only'
make -C /lib/modules/2.6.16-1.2108_FC4smp/build/include/.. SUBDIRS=$PWD SRCROOT=$PWD/. modules
make[1]: Entering directory `/usr/src/kernels/2.6.16-1.2108_FC4-smp-i686'
CC [M] /tmp/vmware-config0/vmnet-only/driver.o
CC [M] /tmp/vmware-config0/vmnet-only/hub.o
CC [M] /tmp/vmware-config0/vmnet-only/userif.o
CC [M] /tmp/vmware-config0/vmnet-only/netif.o
CC [M] /tmp/vmware-config0/vmnet-only/bridge.o
CC [M] /tmp/vmware-config0/vmnet-only/procfs.o
CC [M] /tmp/vmware-config0/vmnet-only/smac_compat.o
CC [M] /tmp/vmware-config0/vmnet-only/smac_linux.x386.o
LD [M] /tmp/vmware-config0/vmnet-only/vmnet.o
Building modules, stage 2.
MODPOST
CC /tmp/vmware-config0/vmnet-only/vmnet.mod.o
LD [M] /tmp/vmware-config0/vmnet-only/vmnet.ko
make[1]: Leaving directory `/usr/src/kernels/2.6.16-1.2108_FC4-smp-i686'
cp -f vmnet.ko ./../vmnet.o
make: Leaving directory `/tmp/vmware-config0/vmnet-only'
The module loads perfectly in the running kernel.

Starting VMware services:
Virtual machine monitor [ OK ]
Virtual ethernet [ OK ]
Bridged networking on /dev/vmnet0 [ OK ]
Bridged networking on /dev/vmnet2 [ OK ]

The configuration of VMware Player 1.0.1 build-19317 for Linux for this running
kernel completed successfully.

You can now run VMware Player by invoking the following command:
"/usr/bin/vmplayer".
...

At this point the mapping should be completed using the "Bridged" connection type. One can perform a check by searching for running VMware Player "vmnet-bridge" processes:

[root@striker ~]# /bin/ps -ef|grep "vmnet-bridge"

root 25526 1 0 07:33 pts/3 00:00:00 /usr/bin/vmnet-bridge -d /var/run/vmnet-bridge-0.pid /dev/vmnet0 eth0
root 25530 1 0 07:33 pts/3 00:00:00 /usr/bin/vmnet-bridge -d /var/run/vmnet-bridge-2.pid /dev/vmnet2 eth1

Finally, after the NST Virtual Machine is started you will need to enable the additional network adapter you have just added for this guest virtual machine. It will most likely be in a disconnected state. Use the VMware Player menu bar to enable the virtual ethernet device by changing its state to: connected.

== What Are The Advantages Of Using VMware Server Instead of VMware Player? ==

The following details the advantages of using VMware Server™ over VMware Player™:

* It allows you to power on virtual machines at system boot. For example, it is possible to turn on a Windows machine with VMware Server™ installed and have the NST Virtual Machine automatically started (you don't need to touch anything but the power button - logging into Windows is not required).
* It allows you to start/stop/use virtual machines from remote computers.
* It allows you to allocate more than one CPU to a virtual machine.
* It provides a full GUI virtual machine editor whereas you need to edit your VMX files in a text editor when using VMware Player™.

HowTo Regenerate The TLS (SSL) Certificate For The NST WUI

2019-11-22T12:30:48Z

Paul Blankenbaker: /* Stricter Trusted Certificate Security Requirements */

__TOC__
= Overview =
This page demonstrates how to regenerate the '''[https://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (Deprecated predecessor: [https://en.wikipedia.org/wiki/SSL SSL])''' self-signing certificate for the NST WUI.

= nstcert =
The process of generating an TLS key and certificate files and then making use of them in a '''[https://en.wikipedia.org/wiki/Apache Apache®]''' configuration file can be a time consuming process. The "'''[http://nst.sourceforge.net/nst/docs/scripts/nstcert.html nstcert]'''" script attempts to automate part of the process by generating template files for use within the Apache® [https://en.wikipedia.org/wiki/Httpd httpd] daemon. The script also generates a '''[https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail PEM (Privacy-enhanced Electronic Mail)]''' file.

= Generate a new TLS Certificate for the NST WUI =
If one needs to generate a new self-signing TLS certificate for NST WUI usage, the following help script: "'''/usr/libexec/nstwui-ssl-gencerts'''" may be utilized. It uses the '''nstcert''' script described above in combination with the configuration file: "'''/etc/nst/wui/nstcert.conf'''". Edit this file to suit your needs.

sudo /usr/libexec/nstwui-ssl-gencerts -r

The "'''-r'''" option is necessary to remove the previous TLS certificate.

= Stricter Trusted Certificate Security Requirements =
<div class="centerBlock"><div class="noteMessage">'''Note:''' One may need to generate a new TLS certificate for the NST WUI do to stricter trusted security requirements (E.g., '''[https://support.apple.com/en-us/HT210176 Requirements for trusted certificates]'''). In particular:

<ul>
<li>The validity period of the new certificate has been reduced to 730 days (2 years).</li>
<li>The Extended Key Usage (extendedKeyUsage) containing the serverAuth OID has been added as required to the extension area of the certificate.</li>
</ul>
<p>Without these changes, newer versions of the Google Chrome browser running on Mac OS (macOS) Catalina may not allow you to connect to the NST web interface.</div></div>

HowTo Use an Android Phone as a GPSd Source

2019-10-15T12:03:30Z

Paul Blankenbaker: /* Summary Configuration Sequence On How Kismet-ng Can Receive GPS Data From the Android GPSd Client App */

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd Service =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

== Summary Configuration Sequence On How Kismet-ng Can Receive GPS Data From the Android GPSd Client App ==

# Configure the Android GPSd Client App for the NST IPv4 Address and Port: 9999.
# Make sure the systemd gpsd.socket unit is started on the NST System and listens for a TCP connection on Port: 2947. Once a connection is established (i.e., a trigger) it will start the systemd gpsd.service. The gpsd process is now the real listener on TCP Port: 2947 for GPS clients (e.g., Kismet-ng).
# Update the gpsd service configuration file: "/etc/sysconfig/gpsd" for a UDP source that accepts packets on Port: 9999. The GPSd Client App will send GPS UDP packets to this port.
# Update the Kismet-ng configuration file: "/etc/kismet/kismet.conf" for GPS data on localhost, Port: 2947. Once Kismet-ng is started, this will be the trigger for the systemd gpsd.socket to start the gpsd.service. Kismet-ng will receive GPS data over Port: 2947.

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

HowTo Use an Android Phone as a GPSd Source

2019-10-15T11:10:17Z

Paul Blankenbaker: /* Configure gpsd.socket */

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd Service =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

HowTo Use an Android Phone as a GPSd Source

2019-10-15T09:18:23Z

Paul Blankenbaker: Removed -N option from /etc/sysconfig/gpsd example config file

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets of containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd.socket =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

HowTo Use an Android Phone as a GPSd Source

2019-10-14T16:04:44Z

Paul Blankenbaker: Cleaned up tabs

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets of containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd.socket =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="-N udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="-N udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

HowTo Use an Android Phone as a GPSd Source

2019-10-14T11:28:20Z

Paul Blankenbaker: Cleaned up size of image

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets of containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd.socket =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="-N udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="-N udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

HowTos

2019-10-14T11:27:09Z

Paul Blankenbaker: Add link to the HowTo page for setting up and Android phone as a GPS source

* [[HowTo Backup And Restore The Master Boot Record (MBR)]]

* [[HowTo BackupPC SSH Key Authentication Setup For rsync Transfer]]
* [[HowTo Change The LVM Volume Group Name That Includes The Root Partition]]
* [[HowTo Configure Apache SSL For davfs, subversion, etc.]]
* [[HowTo Configure and Run a Ring Buffer Capture Session Using: "nstringbufcap"]]
* [[HowTo Create A Patch File For A RPM]]
* [[HowTo Curl Examples]]
* [[HowTo Fix The rngd.service]]
* [[HowTo Determine If Hardware Virtualization Is Enabled]]
* [[HowTo Disable The "relatime" Method For File "atime" Updates]]
* [[HowTo Download From The Command Line Using: "wget"]]
* [[HowTo Dual Boot NST With Windows 8.1]]
* [[HowTo Enable The Gnome Sound Applet]]
* [[HowTo Generate a 3D Pie Chart of nDPI Detected Protocols]]
* [[HowTo Geolocate Data Using The NST WUI]]
* [[HowTo Headless Intel NUC vPro AMT]]
* [[HowTo Install Microsoft PowerShell]]
* [[HowTo Install The MATE (GNOME 2) Desktop]]
* [[HowTo Install VirtualBox]]
* [[HowTo Keep Processes Running After Logging Out Using: "setsid"]]
* [[HowTo Limit Remote Access To "ssh" Connections]]
* [[HowTo Monitor Network Traffic]]
* [[HowTo One Liners]]
* [[HowTo Perform A Security Audit With hping3 (DoS)]]
* [[HowTo Prevent A Laptop Lid Close Suspension]]
* [[HowTo Remote Connect to a Mate Desktop Session Using the Vino Server]]
* [[HowTo Resize The "root" File System Using LVM]]
* [[HowTo Quickly Get A Project Started With Subversion]]
* [[HowTo Quickly Setup A VPN Using WireGuard On NST]]
* [[HowTo Put Multiple Live Images On One USB Memory Stick]]
* [[HowTo Recreate Grub Install And The Master Boot Record (MBR) If Corrupted]]
* [[HowTo Run A Script At Boot]]
* [[OpenVAS | HowTo Setup OpenVAS]]
* [[HowTo Setup An NST System With Multiple Network Interface Adapters Using: "nstnetcfg"]]
* [[HowTo Setup Guacamole]]
* [[HowTo Share A Terminal Session Using Screen]]
* [[HowTo Shutdown NST Using A USB Flash Drive Install For Relocation]]
* [[Upgrade to NST 20|HowTo Upgrade from NST 18 to NST 20]]
* [[HowTo Use an Android Phone as a GPSd Source]]
* [[HowTo Use A Touch Device (iPad) with NST]]
* [[HowTo Use The NST CloudShark Upload Manager]]
* [[HowTo Use The NST Network Tools Widgets]]
* [[NST Mapping Tools | HowTo Use The NST Map Tools Widgets]]
* [[HowTo Use The NST Shell Command Console]]
* [[HowTo Use The NST WUI arp-scan Page To Quickly Locate Hosts]]
* [[HowTo Use The Scapy3k: Multi-Traceroute (MTR)]]
* [[Console Output and Serial Terminals | HowTo Setup Console Output and Serial Terminals]]
* [[DVD_md5sum | HowTo Verify The Md5Sum On An DVD ISO]]
* [[HowTo Install NST 2.16 on an Asus Zenbook Prime]]

HowTo Use an Android Phone as a GPSd Source

2019-10-14T11:26:27Z

Paul Blankenbaker: Initial HowTo on setting up gpsd with an Android phone as the GPS source

This ''HowTo'' details how to use an Android phone as a GPS source for a NST system. Much of the information presented here is based on the [http://www.linux-magazine.com/Issues/2018/210/Tutorial-gpsd Tutorial - gpsd] article found at the [http://www.linux-magazine.com/ Linux Magazine] web site.

= Android Phone Setup =

You will need to run an application on your Android phone that transmits UDP packets of containing information from the GPS in the phone to your NST system. To do this:

# Install [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client by tiagoshibata] from Google Play Store.
# Run the application and set the IPv4 address of the destination to the IPv4 of your NST system and the port number to 9999.

[[File:GPSd Client.png|frame|center|400px|GPSd Client]]

= Verify GPS Data Feed =

Once you have [https://play.google.com/store/apps/details?id=io.github.tiagoshibata.gpsdclient&hl=en_US GPSd Client] configured and running, you should see GPS information arriving on port 9999 on your NST system.

You can use the netcat utility to verify that the information is arriving at your NST system as well as the IPv4 address of your Android phone.

[test@nst ~]$ nc -vlu 9999 2>&1 | head
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Listening on :::9999
Ncat: Listening on 0.0.0.0:9999
Ncat: Connection from 192.168.1.229.
$GPGSV,3,1,12,01,60,094,20,07,45,177,21,11,62,057,17,13,13,291,14*7B

$GPGSV,3,2,12,17,33,254,18,18,45,059,16,28,49,319,16,30,66,234,20*7B

$GPGSV,3,3,12,03,03,135,,08,21,053,,19,14,244,,22,10,115,*7B

[test@nst ~]$

The above output shows that we are receiving GPS information from 192.168.1.229 on port 9999.

= Configure gpsd.socket =

Edit the ''/etc/sysconfig/gpsd'' config file and make sure that the ''OPTIONS'' parameter has a UDP source that accepts packets on port 9999.

# Options for gpsd, including serial devices
OPTIONS="-N udp://*:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

The above configuration accepts UDP packets containing GPS information port 9999 from ''any'' machine on the network. If you know the IPv4 address of your Android phone, you can limit what packets are accepted to just those arriving from your phone by specifying the IPv4 address of your phone in the configuration file. For example, if you phone has an IPv4 address of 192.168.1.229, you can use the following configuration.

# Options for gpsd, including serial devices
OPTIONS="-N udp://192.168.1.229:9999"
# Set to 'true' to add USB devices automatically via udev
USBAUTO="false"

= Verify gpsd.socket Running =

By default, the ''gpsd.socket'' unit should be enabled. You can verify this by running the ''systemctl'' command shown below.

[test@nst ~]$ systemctl status gpsd.socket
● gpsd.socket - GPS (Global Positioning System) Daemon Sockets
Loaded: loaded (/usr/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
Active: active (listening) since Sat 2019-10-12 07:47:06 EDT; 1 day 22h ago
Listen: /var/run/gpsd.sock (Stream)
[::1]:2947 (Stream)
127.0.0.1:2947 (Stream)
Tasks: 0 (limit: 4915)
Memory: 56.0K
CGroup: /system.slice/gpsd.socket

Oct 12 07:47:06 refritos systemd[1]: Listening on GPS (Global Positioning System) Daemon Sockets.
[test@nst ~]$

NOTE: You do not need to enable or start ''gpsd.service''. The ''gpsd.socket'' will take care of starting the necessary processes when clients connect to port 2947 on your NST system.

= Verify Data =

== Using nc ==

You can use the netcat utility (''nc'') to check that you can connect to local gpsd server running on your NST system.

[nst@test ~]$ nc -v 127.0.0.1 2947
Ncat: Version 7.80SVN ( https://nmap.org/ncat )
Ncat: Connected to 127.0.0.1:2947.
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}

== Using Console Clients ==

=== gpspipe ===

The ''gpspipe'' console client from the gps-clients package is useful to see the raw data from a GPS source.

[nst@test ~]$ gpspipe -r | head -10
{"class":"VERSION","release":"3.18.1","rev":"3.18.1","proto_major":3,"proto_minor":13}
{"class":"DEVICES","devices":[{"class":"DEVICE","path":"udp://*:9999","driver":"NMEA0183","activated":"2019-10-14T11:09:22.601Z","flags":1}]}
{"class":"WATCH","enable":true,"json":false,"nmea":true,"raw":0,"scaled":false,"timing":false,"split24":false,"pps":false}
$GPGSV,3,1,09,03,26,052,20,06,68,265,16,12,12,317,14,17,59,037,24*76
$GPGSV,3,2,09,28,46,147,16,02,27,243,,19,62,354,,22,09,040,*7D
$GPGSV,3,3,09,24,15,288,*40
$GLGSV,3,1,10,78,28,319,18,86,24,049,18,76,21,187,13,87,52,334,24*69
$GLGSV,3,2,10,71,23,059,18,70,00,016,,77,54,250,,65,05,153,*60
$GLGSV,3,3,10,88,26,279,,72,23,113,*6B
$GPGGA,110959.0,3546.755123,N,07849.986918,W,2,05,1.2,130.7,M,-49.0,M,,*6D
[nst@test ~]$

=== cgps ===

The ''cgps'' console client from the gpsd-clients package can be used to show time and Console gpsd clients

[nst@test ~]$ cgps
┌───────────────────────────────────────────┐┌──────────────────Seen 20/Used 8┐
│ Time: 2019-10-14T10:58:20.000Z ││ PRN Elev Azim SNR Use │
│ Latitude: 36.17923583 N ││GP 2 23 240 16 Y │
│ Longitude: 79.23310118 W ││GP 6 65 253 16 Y │
│ Altitude: 433.727 ft ││GP 17 61 26 22 Y │
│ Speed: 0.00 mph ││GP 28 51 144 18 Y │
│ Heading: 223.5 deg (true) ││GL 72 18 118 19 Y │
│ Climb: 39.37 ft/min ││GL 77 56 261 14 Y │
│ Status: 3D DIFF FIX (6 secs) ││GL 78 24 323 22 Y │
│ Long Err (XDOP, EPX): 0.62, +/- 10.0 ft ││GL 86 28 43 15 Y │
│ Lat Err (YDOP, EPY): 0.74, +/- 10.9 ft ││GP 1 0 49 0 N │
│ Alt Err (VDOP, EPV): 0.90, +/- 17.0 ft ││GP 3 29 57 14 N │
│ 2D Err (HDOP, CEP): 1.00, +/- 14.8 ft ││GP 12 7 317 0 N │
│ 3D Err (PDOP, SEP): 1.30, +/- 22.5 ft ││GP 19 60 341 0 N │
│ Time Err (TDOP): 1.02 ││GP 22 13 42 0 N │
│ Geo Err (GDOP): 2.08 ││GP 24 15 293 0 N │
│ Speed Err (EPS): +/- 14.8 mph││ 65 0 156 0 N │
│ Head Err (EPD): n/a ││GL 70 3 21 0 N │
│ Time offset: -35.457 sec ││GL 71 22 66 0 N │
│ Grid Square: FM05os ││GL 76 28 188 19 N │
└───────────────────────────────────────────┘└More...──────────────────────────┘
{"class":"TPV","device":"udp://*:9999","status":2,"mode":3,"time":"2019-10-14T10
:58:20.000Z","ept":0.005,"lat":35.779235833,"lon":-78.833101183,"alt":132.200,"e
px":3.055,"epy":3.314,"epv":5.175,"track":223.5000,"magtrack":223.5000,"speed":0
.000,"climb":0.200,"eps":6.63,"epc":10.35}

=== gpsmon ===

The ''gpsmon'' console client from the gpsd package can also be used to get information about the GPS source.

[nst@test ~]$ gpsmon
tcp://localhost:2947 NMEA0183>
┌──────────────────────────────────────────────────────────────────────────────┐
│Time: 2019-10-14T11:06:05.000Z Lat: 35 46' 45.02561" Non: 78 49' 59.01454" W│
└───────────────────────────────── Cooked TPV ─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ GPGSV GLGSV GPGGA GNGNS GPVTG GPRMC GPGSA GNGSA │
└───────────────────────────────── Sentences ──────────────────────────────────┘
┌──────────────────┐┌────────────────────────────┐┌────────────────────────────┐
│Ch PRN Az El S/N ││Time: 110605.0 ││Time: 110605.0 │
│ 0 3 53 27 15 ││Latitude: 3546.754270 N ││Latitude: 3546.754270 │
│ 1 6 261 67 15 ││Longitude: 07849.985758 W ││Longitude: 07849.985758 │
│ 2 12 317 10 13 ││Speed: 0.0 ││Altitude: 130.1 │
│ 3 17 35 60 15 ││Course: 223.5 ││Quality: 2 Sats: 05 │
│ 4 19 350 61 12 ││Status: A FAA: D ││HDOP: 2.2 │
│ 5 24 289 15 15 ││MagVar: 0.0 E ││Geoid: -49.0 │
│ 6 28 147 47 12 │└─────────── RMC ────────────┘└─────────── GGA ────────────┘
│ 7 2 243 26 0 │┌────────────────────────────┐┌────────────────────────────┐
│ 8 22 40 10 0 ││Mode: A2 Sats: ││UTC: RMS: │
│ 9 70 18 1 0 ││DOP: H=2.3 V=0.9 P=2.5 ││MAJ: MIN: │
│10 77 253 54 0 ││TOFF: -35.113007340 ││ORI: LAT: │
│11 65 154 3 0 ││PPS: ││LON: ALT: │
└────── GSV ───────┘└──────── GSA + PPS ─────────┘└─────────── GST ────────────┘
(49) $GPGSA,A,2,03,06,17,19,24,,,,,,,,2.5,2.3,0.9*31
(70) $GPGSV,3,1,09,03,27,053,15,06,67,261,15,12,10,317,13,17,60,035,15*77

== GUI gpsd clients ==

There are several GUI Clients as well.

* ''xgps'' - Similar to ''cgps'' but has a graphical view of satellite locations.
* ''xgpsspeed'' - A graphical ''speedometer'' with satellite overlay.
* ''gpsdrive'' - A mapping application.

= Kismet Configuration =

To enable ''kismet-ng'' to make use of the location and time information provided by ''gpsd'', edit the ''/etc/kismet/kismet.conf'' file and make sure that the ''gps'' parameter is set as shown below.

# New GPS configuration
# gps=type:options
#
gps=gpsd:host=localhost,port=2947

= Running gpsd By Hand =

If you need to run ''gpsd'' by hand, you will need to disable the ''gpsd.socket'' unit first. If you don't do this, ''systemd'' will hold port 2947 open and prevent your instance of ''gpsd'' from being able to bind to it.

systemctl stop gpsd.socket

After disabling the ''gpsd.socket'' unit, you can run ''gpsd'' in the foreground with debug output enabled as follows.

gpsd -D9 -N "udp://*:9999"

Or, if you want to limit the GPS source to a specific IPv4 address, substitute the IPv4 address from the ''*''.

gpsd -D9 -N udp://192.168.1.229:9999

File:GPSd Client.png

2019-10-14T10:28:03Z

Paul Blankenbaker:

GPSd Client configured to send UDP packets to port 9999

MediaWiki Backup And Restore

2019-08-21T11:19:35Z

Paul Blankenbaker: Added notes about images directory

= Backup =

The system which contains the NST WIKI performs nightly backups. The compressed back up files under the ''/var/nst/nstwiki_archive'' directory.

The ''/var/nst/nstwiki_archive'' directory is then mirrored at external locations.

The following items are backed up:

* The SQL database associated with the Wiki.
* The configuration files associated with the Wiki.
* The media files (images) associated with the Wiki.

Here is an example of using '''rsync''' to download a copy of the back up files:

[nst@nst30-repo ~]$ rsync -avhP nstwiki:/var/nst/nstwiki_archive backup/nst30-repo
receiving incremental file list
nstwiki_archive/
nstwiki_archive/nstwiki_conf_archive0.tgz
117.14M 100% 3.94MB/s 0:00:28 (xfr#1, to-chk=1/3)
nstwiki_archive/nstwiki_media_archive0.tgz
694.91M 100% 3.99MB/s 0:02:46 (xfr#2, to-chk=0/3)

sent 66 bytes received 812.24M bytes 4.13M bytes/sec
total size is 812.05M speedup is 1.00
[nst@nst30-repo ~]$ ls -l backup/nst30-repo/nstwiki_archive
total 793020
-rw-r--r-- 1 nst nst 117138773 Aug 21 05:34 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 nst nst 694906230 Aug 21 05:34 nstwiki_media_archive0.tgz
[nst@nst30-repo ~]$

= Restore/Move =

If you need to restore the NST Wiki or need to relocate the NST Wiki to another machine, use the following strategy:

* Set up MediaWiki on the other machine by following the instructions on the [[MediaWiki]] page.
* Stop the ''httpd'' service.
* Stop the ''mysqld'' service.
* Transfer and install from the back up archives.
* Start the ''mysqld'' service.
* Run any new MediaWiki database upgrade scripts (if you are moving to a newer version of MediaWiki).
* Update your LocalSettings.php file.
* Start the ''httpd'' service.

== Set Up MediaWiki ==

If you are moving the NST Wiki to a new machine, you will need to set up MediaWiki on the new machine:

* Before setting up MediaWiki, review the ''LocalSettings.php'' file as you will likely want to match some of the settings (if you don't it's not the end of the world - but if you take the time now it might save you some tweaks later).
* See the [[MediaWiki]] page for details on setting up MediaWiki on a NST system.
* Install the [http://www.mediawiki.org/wiki/Extension:EmbedVideo EmbedVideo] media extension.

== Stop Services ==

Stop the ''httpd'' and ''mysqld'' services as shown below (use ''service'' instead of ''systemctl'' if you are on a older system):

[root@probe-p3p1 ~]# systemctl stop httpd.service
[root@probe-p3p1 ~]# systemctl stop mysqld.service
[root@probe-p3p1 ~]#

== Transfer And Extract The Backup Archives ==

Get a copy of the NST Wiki backup files from the directory ''/var/nst/nstwiki_archive'' directory and transfer them to your ''/tmp'' directory:

[root@probe-p3p1 ~]# rsync -rp nstwiki:/tmp/nstwiki_archive /tmp/
root@nstwiki's password:
[root@probe-p3p1 ~]# ls -l /tmp/nstwiki_archive
total 198476
-rw-r--r-- 1 root root 66375294 Oct 22 18:32 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 root root 126201929 Oct 22 18:32 nstwiki_media_archive0.tgz
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_conf_archive0.tgz'' file to the ''/var/nst/backup directory'':

[root@probe-p3p1 ~]# install -d /var/nst/backup
[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_conf_archive0.tgz -C /var/nst/backup/ .
[root@probe-p3p1 ~]#

Create and initialize the ''/var/nst/mediawiki directory'':

[root@probe-p3p1 ~]# install -d /var/nst/mediawiki
[root@probe-p3p1 ~]# mw-createinstance /var/nst/mediawiki
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_media_archive0.tgz'' file to the directory where your MediaWiki files live.

[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_media_archive0.tgz -C /var/nst/mediawiki
[root@probe-p3p1 ~]#

Add a sym-link to the ''images'' directory under ''/usr/share/mediawiki'' (still not sure why this is required). Also, you may need to edit/save each NST WIKI page if thumbnails are not being created automatically.

[root@probe-p3p1 ~]# mv /usr/share/mediawiki/images /usr/share/mediawiki/images.orig
[root@probe-p3p1 ~]# ln /var/nst/mediawiki/images /usr/share/mediawiki/images
[root@probe-p3p1 ~]#

== Restore The NST Wiki Database ==

At this point you can start up the ''mysqld'' service and restore the most recent version of the NST Wiki backup. However, before you can restore using the SQL file you will need to drop the ''wikidb'' (or whatever you named your database) if it exists:

[root@probe-p3p1 ~]# systemctl start mysqld.service
[root@probe-p3p1 ~]# mysql -h 127.0.0.1 --user=root --password
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 5.5.14 MySQL Community Server (GPL)

Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> drop database wikidb;
Query OK, 45 rows affected (0.15 sec)

mysql> \q
Bye
[root@probe-p3p1 ~]#

At this point you can restore the NST Wiki database:

[root@probe-p3p1 ~]# gzip -dc < /var/nst/backup/db/nstwikidb.sql.gz | mysql -h 127.0.0.1 --user=root --password
Enter password:
[root@probe-p3p1 ~]#

== Update The NST Wiki Database ==

If the location you are restoring the database to uses a newer version of MediaWiki, you will likely need to run the MediaWiki upgrade commands. Review the ''/usr/share/doc/mediawiki/UPGRADE'' file. Most likely you will need to run the following commands:

[root@probe-p3p1 ~]# cd /usr/share/mediawiki/maintenance/
[root@probe-p3p1 maintenance]# php update.php
A copy of your installation's LocalSettings.php
must exist and be readable in the source directory.
[root@probe-p3p1 maintenance]# php update.php --conf /var/nst/mediawiki/LocalSettings.php
MediaWiki 1.16.5 Updater

Going to run database updates for wikidb
Depending on the size of your database this may take a while!

... Lot's of output as database is updated ...

Purging caches...done.
Done.
[root@probe-p3p1 maintenance]# cd
[root@probe-p3p1 ~]#

== Update LocalSettings.php ==

Before starting up the web server, you will want to review your ''LocalSettings.php'' file:

* Compare it with the back up you made earlier (''/root/LocalSettings.php.working'').
* Initially disable any extensions currently configured (you may need to install the extension modules before enabling).
* Review the contents of ''/usr/share/mediawiki/includes/DefaultSettings.php'' to see if there are any new settings you need to add.

[root@probe-p3p1 ~]# emacs -nw /var/nst/mediawiki/LocalSettings.php LocalSettings.php.working
[root@probe-p3p1 ~]#

Also, for some reason a copy of the ''LocalSettings.php'' file also needs to be under the ''/usr/share/mediawiki'' (at least for MediaWiki 1.33 and Fedora 30 packaging).

[root@probe-p3p1 ~]# ln /var/nst/mediawiki/LocalSettings.php /usr/share/mediawiki/LocalSettings.php
[root@probe-p3p1 ~]#

== Restart The Web Service And Test ==

At this point you should be able to restart the web service and PHP engine and test your installation:

[root@probe-p3p1 ~]# systemctl start httpd.service
[root@probe-p3p1 ~]# systemctl restart php-fpm.service
[root@probe-p3p1 ~]# firefox http://127.0.0.1/wiki
[root@probe-p3p1 ~]#

At this point you should be able to review the contents of the Wiki and determine what is broken (not working) and then try to figure out what you need to do in:

* Examine log files under the ''/var/log/httpd'' directory - they will often provide useful clues.
* The ''/var/nst/mediawiki/LocalSettings.php'' file (look for new values you might need to override in ''/usr/share/mediawiki/includes/DefaultSettings.php''). Also, consider temporarily enabling the debug logging feature with:
# Uncomment to enable debug log file when trouble shooting
$wgDebugLogFile = "/var/log/httpd/debug-wikidb.log";
* Review the ''/etc/httpd/conf/httpd.conf'' file.
* Review your mediawiki configuration file under the ''/etc/httpd/conf.d'' directory (''nstwiki.conf'').

MediaWiki Backup And Restore

2019-08-21T10:34:15Z

Paul Blankenbaker: /* Backup */

= Backup =

The system which contains the NST WIKI performs nightly backups. The compressed back up files under the ''/var/nst/nstwiki_archive'' directory.

The ''/var/nst/nstwiki_archive'' directory is then mirrored at external locations.

The following items are backed up:

* The SQL database associated with the Wiki.
* The configuration files associated with the Wiki.
* The media files (images) associated with the Wiki.

Here is an example of using '''rsync''' to download a copy of the back up files:

[nst@nst30-repo ~]$ rsync -avhP nstwiki:/var/nst/nstwiki_archive backup/nst30-repo
receiving incremental file list
nstwiki_archive/
nstwiki_archive/nstwiki_conf_archive0.tgz
117.14M 100% 3.94MB/s 0:00:28 (xfr#1, to-chk=1/3)
nstwiki_archive/nstwiki_media_archive0.tgz
694.91M 100% 3.99MB/s 0:02:46 (xfr#2, to-chk=0/3)

sent 66 bytes received 812.24M bytes 4.13M bytes/sec
total size is 812.05M speedup is 1.00
[nst@nst30-repo ~]$ ls -l backup/nst30-repo/nstwiki_archive
total 793020
-rw-r--r-- 1 nst nst 117138773 Aug 21 05:34 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 nst nst 694906230 Aug 21 05:34 nstwiki_media_archive0.tgz
[nst@nst30-repo ~]$

= Restore/Move =

If you need to restore the NST Wiki or need to relocate the NST Wiki to another machine, use the following strategy:

* Set up MediaWiki on the other machine by following the instructions on the [[MediaWiki]] page.
* Stop the ''httpd'' service.
* Stop the ''mysqld'' service.
* Transfer and install from the back up archives.
* Start the ''mysqld'' service.
* Run any new MediaWiki database upgrade scripts (if you are moving to a newer version of MediaWiki).
* Update your LocalSettings.php file.
* Start the ''httpd'' service.

== Set Up MediaWiki ==

If you are moving the NST Wiki to a new machine, you will need to set up MediaWiki on the new machine:

* Before setting up MediaWiki, review the ''LocalSettings.php'' file as you will likely want to match some of the settings (if you don't it's not the end of the world - but if you take the time now it might save you some tweaks later).
* See the [[MediaWiki]] page for details on setting up MediaWiki on a NST system.
* Install the [http://www.mediawiki.org/wiki/Extension:EmbedVideo EmbedVideo] media extension.

== Stop Services ==

Stop the ''httpd'' and ''mysqld'' services as shown below (use ''service'' instead of ''systemctl'' if you are on a older system):

[root@probe-p3p1 ~]# systemctl stop httpd.service
[root@probe-p3p1 ~]# systemctl stop mysqld.service
[root@probe-p3p1 ~]#

== Transfer And Extract The Backup Archives ==

Get a copy of the NST Wiki backup files from the directory ''/var/nst/nstwiki_archive'' directory and transfer them to your ''/tmp'' directory:

[root@probe-p3p1 ~]# rsync -rp nstwiki:/tmp/nstwiki_archive /tmp/
root@nstwiki's password:
[root@probe-p3p1 ~]# ls -l /tmp/nstwiki_archive
total 198476
-rw-r--r-- 1 root root 66375294 Oct 22 18:32 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 root root 126201929 Oct 22 18:32 nstwiki_media_archive0.tgz
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_conf_archive0.tgz'' file to the ''/var/nst/backup directory'':

[root@probe-p3p1 ~]# install -d /var/nst/backup
[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_conf_archive0.tgz -C /var/nst/backup/ .
[root@probe-p3p1 ~]#

Create and initialize the ''/var/nst/mediawiki directory'':

[root@probe-p3p1 ~]# install -d /var/nst/mediawiki
[root@probe-p3p1 ~]# mw-createinstance /var/nst/mediawiki
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_media_archive0.tgz'' file to the directory where your MediaWiki files live.

[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_media_archive0.tgz -C /var/nst/mediawiki
[root@probe-p3p1 ~]#

== Restore The NST Wiki Database ==

At this point you can start up the ''mysqld'' service and restore the most recent version of the NST Wiki backup. However, before you can restore using the SQL file you will need to drop the ''wikidb'' (or whatever you named your database) if it exists:

[root@probe-p3p1 ~]# systemctl start mysqld.service
[root@probe-p3p1 ~]# mysql -h 127.0.0.1 --user=root --password
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 5.5.14 MySQL Community Server (GPL)

Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> drop database wikidb;
Query OK, 45 rows affected (0.15 sec)

mysql> \q
Bye
[root@probe-p3p1 ~]#

At this point you can restore the NST Wiki database:

[root@probe-p3p1 ~]# gzip -dc < /var/nst/backup/db/nstwikidb.sql.gz | mysql -h 127.0.0.1 --user=root --password
Enter password:
[root@probe-p3p1 ~]#

== Update The NST Wiki Database ==

If the location you are restoring the database to uses a newer version of MediaWiki, you will likely need to run the MediaWiki upgrade commands. Review the ''/usr/share/doc/mediawiki/UPGRADE'' file. Most likely you will need to run the following commands:

[root@probe-p3p1 ~]# cd /usr/share/mediawiki/maintenance/
[root@probe-p3p1 maintenance]# php update.php
A copy of your installation's LocalSettings.php
must exist and be readable in the source directory.
[root@probe-p3p1 maintenance]# php update.php --conf /var/nst/mediawiki/LocalSettings.php
MediaWiki 1.16.5 Updater

Going to run database updates for wikidb
Depending on the size of your database this may take a while!

... Lot's of output as database is updated ...

Purging caches...done.
Done.
[root@probe-p3p1 maintenance]# cd
[root@probe-p3p1 ~]#

== Update LocalSettings.php ==

Before starting up the web server, you will want to review your ''LocalSettings.php'' file:

* Compare it with the back up you made earlier (''/root/LocalSettings.php.working'').
* Initially disable any extensions currently configured (you may need to install the extension modules before enabling).
* Review the contents of ''/usr/share/mediawiki/includes/DefaultSettings.php'' to see if there are any new settings you need to add.

[root@probe-p3p1 ~]# emacs -nw /var/nst/mediawiki/LocalSettings.php LocalSettings.php.working
[root@probe-p3p1 ~]#

Also, for some reason a copy of the ''LocalSettings.php'' file also needs to be under the ''/usr/share/mediawiki'' (at least for MediaWiki 1.33 and Fedora 30 packaging).

[root@probe-p3p1 ~]# ln /var/nst/mediawiki/LocalSettings.php /usr/share/mediawiki/LocalSettings.php
[root@probe-p3p1 ~]#

== Restart The Web Service And Test ==

At this point you should be able to restart the web service and PHP engine and test your installation:

[root@probe-p3p1 ~]# systemctl start httpd.service
[root@probe-p3p1 ~]# systemctl restart php-fpm.service
[root@probe-p3p1 ~]# firefox http://127.0.0.1/wiki
[root@probe-p3p1 ~]#

At this point you should be able to review the contents of the Wiki and determine what is broken (not working) and then try to figure out what you need to do in:

* Examine log files under the ''/var/log/httpd'' directory - they will often provide useful clues.
* The ''/var/nst/mediawiki/LocalSettings.php'' file (look for new values you might need to override in ''/usr/share/mediawiki/includes/DefaultSettings.php''). Also, consider temporarily enabling the debug logging feature with:
# Uncomment to enable debug log file when trouble shooting
$wgDebugLogFile = "/var/log/httpd/debug-wikidb.log";
* Review the ''/etc/httpd/conf/httpd.conf'' file.
* Review your mediawiki configuration file under the ''/etc/httpd/conf.d'' directory (''nstwiki.conf'').

MediaWiki Backup And Restore

2019-08-21T10:08:10Z

Paul Blankenbaker: Updated based on restore to NST 30 machine

= Backup =

The system which contains the NST WIKI performs nightly backups. The compressed back up files under the ''/var/nst/nstwiki_archive'' directory.

The ''/var/nst/nstwiki_archive'' directory is then mirrored at external locations.

The following items are backed up:

* The SQL database associated with the Wiki.
* The configuration files associated with the Wiki.
* The media files (images) associated with the Wiki.

Here is an example of using '''rsync''' to download a copy of the back up files:

[nst@nst30-repo ~]$ rsync -avhP nstwiki:/var/nst/nstwiki_archive backup/nst30-repo
receiving incremental file list
nstwiki_archive/
nstwiki_archive/nstwiki_conf_archive0.tgz
117.14M 100% 3.94MB/s 0:00:28 (xfr#1, to-chk=1/3)
nstwiki_archive/nstwiki_media_archive0.tgz
694.91M 100% 3.99MB/s 0:02:46 (xfr#2, to-chk=0/3)

sent 66 bytes received 812.24M bytes 4.13M bytes/sec
total size is 812.05M speedup is 1.00
[nst@nst30-repo ~]$ ls -l backup/nst30-repo/nstwiki_archive
total 793020
-rw-r--r-- 1 nst nst 117138773 Aug 21 05:34 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 nst nst 694906230 Aug 21 05:34 nstwiki_media_archive0.tgz
[nst@nst30-repo ~]$

= Restore/Move =

If you need to restore the NST Wiki or need to relocate the NST Wiki to another machine, use the following strategy:

* Set up MediaWiki on the other machine by following the instructions on the [[MediaWiki]] page.
* Stop the ''httpd'' service.
* Stop the ''mysqld'' service.
* Transfer and install from the back up archives.
* Start the ''mysqld'' service.
* Run any new MediaWiki database upgrade scripts (if you are moving to a newer version of MediaWiki).
* Update your LocalSettings.php file.
* Start the ''httpd'' service.

== Set Up MediaWiki ==

If you are moving the NST Wiki to a new machine, you will need to set up MediaWiki on the new machine:

* Before setting up MediaWiki, review the ''LocalSettings.php'' file as you will likely want to match some of the settings (if you don't it's not the end of the world - but if you take the time now it might save you some tweaks later).
* See the [[MediaWiki]] page for details on setting up MediaWiki on a NST system.
* Install the [http://www.mediawiki.org/wiki/Extension:EmbedVideo EmbedVideo] media extension.

== Stop Services ==

Stop the ''httpd'' and ''mysqld'' services as shown below (use ''service'' instead of ''systemctl'' if you are on a older system):

[root@probe-p3p1 ~]# systemctl stop httpd.service
[root@probe-p3p1 ~]# systemctl stop mysqld.service
[root@probe-p3p1 ~]#

== Transfer And Extract The Backup Archives ==

Get a copy of the NST Wiki backup files from the directory ''/var/nst/nstwiki_archive'' directory and transfer them to your ''/tmp'' directory:

[root@probe-p3p1 ~]# rsync -rp nstwiki:/tmp/nstwiki_archive /tmp/
root@nstwiki's password:
[root@probe-p3p1 ~]# ls -l /tmp/nstwiki_archive
total 198476
-rw-r--r-- 1 root root 66375294 Oct 22 18:32 nstwiki_conf_archive0.tgz
-rw-r--r-- 1 root root 126201929 Oct 22 18:32 nstwiki_media_archive0.tgz
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_conf_archive0.tgz'' file to the ''/var/nst/backup directory'':

[root@probe-p3p1 ~]# install -d /var/nst/backup
[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_conf_archive0.tgz -C /var/nst/backup/ .
[root@probe-p3p1 ~]#

Create and initialize the ''/var/nst/mediawiki directory'':

[root@probe-p3p1 ~]# install -d /var/nst/mediawiki
[root@probe-p3p1 ~]# mw-createinstance /var/nst/mediawiki
[root@probe-p3p1 ~]#

Extract the contents of the ''nstwiki_media_archive0.tgz'' file to the directory where your MediaWiki files live.

[root@probe-p3p1 ~]# tar xzf /tmp/nstwiki_archive/nstwiki_media_archive0.tgz -C /var/nst/mediawiki
[root@probe-p3p1 ~]#

== Restore The NST Wiki Database ==

At this point you can start up the ''mysqld'' service and restore the most recent version of the NST Wiki backup. However, before you can restore using the SQL file you will need to drop the ''wikidb'' (or whatever you named your database) if it exists:

[root@probe-p3p1 ~]# systemctl start mysqld.service
[root@probe-p3p1 ~]# mysql -h 127.0.0.1 --user=root --password
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 5.5.14 MySQL Community Server (GPL)

Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> drop database wikidb;
Query OK, 45 rows affected (0.15 sec)

mysql> \q
Bye
[root@probe-p3p1 ~]#

At this point you can restore the NST Wiki database:

[root@probe-p3p1 ~]# gzip -dc < /var/nst/backup/db/nstwikidb.sql.gz | mysql -h 127.0.0.1 --user=root --password
Enter password:
[root@probe-p3p1 ~]#

== Update The NST Wiki Database ==

If the location you are restoring the database to uses a newer version of MediaWiki, you will likely need to run the MediaWiki upgrade commands. Review the ''/usr/share/doc/mediawiki/UPGRADE'' file. Most likely you will need to run the following commands:

[root@probe-p3p1 ~]# cd /usr/share/mediawiki/maintenance/
[root@probe-p3p1 maintenance]# php update.php
A copy of your installation's LocalSettings.php
must exist and be readable in the source directory.
[root@probe-p3p1 maintenance]# php update.php --conf /var/nst/mediawiki/LocalSettings.php
MediaWiki 1.16.5 Updater

Going to run database updates for wikidb
Depending on the size of your database this may take a while!

... Lot's of output as database is updated ...

Purging caches...done.
Done.
[root@probe-p3p1 maintenance]# cd
[root@probe-p3p1 ~]#

== Update LocalSettings.php ==

Before starting up the web server, you will want to review your ''LocalSettings.php'' file:

* Compare it with the back up you made earlier (''/root/LocalSettings.php.working'').
* Initially disable any extensions currently configured (you may need to install the extension modules before enabling).
* Review the contents of ''/usr/share/mediawiki/includes/DefaultSettings.php'' to see if there are any new settings you need to add.

[root@probe-p3p1 ~]# emacs -nw /var/nst/mediawiki/LocalSettings.php LocalSettings.php.working
[root@probe-p3p1 ~]#

Also, for some reason a copy of the ''LocalSettings.php'' file also needs to be under the ''/usr/share/mediawiki'' (at least for MediaWiki 1.33 and Fedora 30 packaging).

[root@probe-p3p1 ~]# ln /var/nst/mediawiki/LocalSettings.php /usr/share/mediawiki/LocalSettings.php
[root@probe-p3p1 ~]#

== Restart The Web Service And Test ==

At this point you should be able to restart the web service and PHP engine and test your installation:

[root@probe-p3p1 ~]# systemctl start httpd.service
[root@probe-p3p1 ~]# systemctl restart php-fpm.service
[root@probe-p3p1 ~]# firefox http://127.0.0.1/wiki
[root@probe-p3p1 ~]#

At this point you should be able to review the contents of the Wiki and determine what is broken (not working) and then try to figure out what you need to do in:

* Examine log files under the ''/var/log/httpd'' directory - they will often provide useful clues.
* The ''/var/nst/mediawiki/LocalSettings.php'' file (look for new values you might need to override in ''/usr/share/mediawiki/includes/DefaultSettings.php''). Also, consider temporarily enabling the debug logging feature with:
# Uncomment to enable debug log file when trouble shooting
$wgDebugLogFile = "/var/log/httpd/debug-wikidb.log";
* Review the ''/etc/httpd/conf/httpd.conf'' file.
* Review your mediawiki configuration file under the ''/etc/httpd/conf.d'' directory (''nstwiki.conf'').

HowTo One Liners

2019-07-31T14:54:52Z

Paul Blankenbaker: Added rmsshhost function

__TOC__
= Overview =
This page provides a quick reference to common '''One Liner''' administrative command line operations.

= Get Syntax Color In Less =

The NST includes the source-highlight package which can "smartly" apply color to a wide variety of file formats. You can set some '''less''' environment variables to make use of the source-hightlight package to color code files in your terminal with the following settings:

export LESSOPEN="| source-highlight --out-format=esc -o STDOUT -i %s 2>/dev/null"; export LESS=" -R "

Then try something like:

less /usr/share/nstwui/apps/arp-scan/arp-scan.js
less /usr/bin/lsusb.py

Unfortunately, source-highlight only works by filename extensions (it won't try to guess the input format based on the contents of the file).

= Find The Largest Files Within A File System =
This example finds the 10 largest files, descending sorted, using the "'''/var'''" top level directory:
[root@vortex wui]# find /var -printf '%s %p\n' | sort -nr | head -10;
29956694633 /var/named/chroot/var/named/data/default_debug.log
182947840 /var/lib/rpm/Packages
134217728 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-00000000000b1d98-0005092323239c17.journal
125829120 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-000000000008eadb-000506c496be90cb.journal
125829120 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-00000000000251f3-0004f57678d900a6.journal
125829120 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-0000000000000001-0004f10922bc1e86.journal
95967232 /var/cache/yum/x86_64/20/fedora/gen/primary_db.sqlite
83886080 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-0000000000077d06-00050460486ab015.journal
75497472 /var/log/journal/597d443ff603490286135ca186ed9c7d/system@f9cb0e593f6c413d8fdfaa88bd1c9f42-000000000004d2bc-0004fbc9efdbc627.journal
64720632 /var/lib/clamav/main.cvd

= Remove Incorrect Host Key from ~/.ssh/known_hosts (Delete 1 Line from File) =

The ''sed'' command can be very useful when you want to remove a specific line from a file. For example, the following command can be used to remove line 12 out of the file: ''~/.ssh/known_hosts''.

sed -i -e 12d ~/.ssh/known_hosts

Alternatively, you can add a ''rmsshhost'' function to your ''~/.bash_profile'':

rmsshhost() {
sed -i -e ${1:-999999999}d ${2:-~/.ssh/known_hosts};
}

This is particularly useful in situations where ''ssh'' host keys are expected to change. For example, depending on which micro SD card is loaded on a Beagle Bone Black, it's host key might change. The following demonstrates the output from ''ssh'' when it detects this change in the host key (note how it reports the problem line as 54). The ''sed'' command is then used to quickly remove the old key.

taco:~ pkb$ ssh salsa-e
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
fb:a7:a9:09:1a:f3:d2:4a:aa:89:9d:34:47:1c:d5:3c.
Please contact your system administrator.
Add correct host key in /Users/pkb/.ssh/known_hosts to get rid of this message.
Offending RSA key in /Users/pkb/.ssh/known_hosts:54
Password authentication is disabled to avoid man-in-the-middle attacks.
Keyboard-interactive authentication is disabled to avoid man-in-the-middle attacks.
Agent forwarding is disabled to avoid man-in-the-middle attacks.
X11 forwarding is disabled to avoid man-in-the-middle attacks.
Debian GNU/Linux 7

BeagleBoard.org Debian Image 2015-03-01

Support/FAQ: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian

default username:password is [debian:temppwd]

Permission denied (publickey,password).
(reverse-i-search)`se': cd release/
taco:~ pkb$ sed -i -e 54d ~/.ssh/known_hosts
taco:~ pkb$

Or, if using the ''rmsshhost'' function, you can remove line 54 using the following command:

rmsshhost 54

= Find File Differences in Two Directories =

This one is handy when you have two directories (''DIRA'' and ''DIRB'') with a similar set of files and you want to determine if any of the files in ''DIRB'' are different than the files in ''DIRA''. As an example, if you are looking for differences in your CSS files under the css directory (''DIRA'') with the css files in the 1.1.7 release found at ../1.1.7/css (''DIRB'').

[root@rice 1.1.4]# find css -type f | wc -l
4
[root@rice 1.1.4]# find css -type f | while read src; do cmp ${src} ../1.1.7/${src}; done
css/site.css ../1.1.7/css/site.css differ: byte 31, line 3
[root@rice 1.1.4]#

= One Liner Resources =

* '''[http://www.grymoire.com/Unix/Regular.html A Regular Expression Reference]'''

* '''[https://regexr.com/ Regular Expression Online Tool]'''

* '''[http://main.rtfiber.com.tw/~changyj/sed/ Sed and Regular Expressions]'''

* '''[https://www.tutorialspoint.com/unix/unix-regular-expressions.htm Linux - Regular Expressions Tutorial with Sed]'''

* '''[https://eloquentjavascript.net/09_regexp.html A Javascript Regular Expressions Tutorial]

* Handy One Liners for Sed: '''[http://www.linuxhowtos.org/System/sedoneliner.htm Sed - LinuxHowtos]''', '''[http://sed.sourceforge.net/sed1line.txt Sed - SourceForge]''', '''[https://gist.github.com/jasonm23/396693/b9135d0dbe821d2ff8bd1b8a0a452cb27b4c2f68 Sed - Gist]'''

* '''[https://www.gnu.org/software/sed/ GNU Sed Homepage]'''

* '''[http://www.grymoire.com/Unix/Sed.html A Sed Tutorial]'''

* '''[http://www.ibm.com/developerworks/linux/library/l-sed1/index.html Sed Part1]''', '''[http://www.ibm.com/developerworks/linux/library/l-sed2/index.html Sed Part2]''' and '''[http://www.ibm.com/developerworks/linux/library/l-sed3/index.html Sed Part3]'''

* '''[https://posts.specterops.io/fawk-yeah-advanced-sed-and-awk-usage-parsing-for-pentesters-3-e5727e11a8ad Advanced Parsing for Pentesters]'''

* '''[https://www.gnu.org/software/gawk/ GNU Gawk Homepage]'''

* '''[https://www.gnu.org/software/gawk/manual/gawk.html The GNU Awk User’s Guide]'''

* '''[http://www.grymoire.com/Unix/Awk.html An Awk Tutorial]'''

* '''[http://www.thegeekstuff.com/2010/03/awk-arrays-explained-with-5-practical-examples Awk Array Examples]'''

* '''[https://www.ibm.com/developerworks/library/l-lpic1-103-2/l-lpic1-103-2-pdf.pdf Text Streams and Filters]'''

* '''[http://www.grymoire.com/Unix/Grep.html A Grep Tutorial]'''

* '''[http://www.grymoire.com/Unix/Find.html A Find Example]'''

* '''[http://www.grymoire.com/Unix/Tar.html A Tar Tutorial]'''

OpenVAS

2019-07-19T10:28:44Z

Paul Blankenbaker: Verified that instructions work on NST 30

= Overview =

The Open Vulnerability Assessment Scanner ([http://www.openvas.com OpenVAS]) and Greenbone Security tools provide the following capabilities:

* Scan systems on your network looking for security risks.
* Manage and update the rule sets used for the scans.
* Produce reports based on the scans.
* Schedule periodic scans.
* Interact with the system via the command line, a desktop GUI interface, or a web based front end.

The [http://www.openvas.com OpenVAS] project is a branch of the original [http://www.nessus.org/ Nessus] software. More information can be found at http://www.openvas.com/.

The [http://www.openvas.com OpenVAS] software package was included in the NST distribution starting with the 2.15.0 release.

[[Image:Warning.png‎]] You should only setup your NST system for OpenVAS after performing a hard disk installation (within a virtual machine is OK). If you attempt to setup OpenVAS on a ''live'' boot you will likely run out of memory and lock your system.

== Quick Tip On Getting Started ==

# Define a target.
# Define a Task.
# Run Task.

= '''NST 30, NST 28 and NST 26 Setup''' =

Getting OpenVAS (http://openvas.org) and Greenbone (https://www.greenbone.net/) set up and working on a NST 26 or Fedora 26 based system is a non-trivial task and involves some time (plan on 60 minutes). While the instructions below are based on a successful set up, due to the dynamic nature of all the packages and systems involved adjustments may need to be made in the future. Repeated use of the ''openvas-check-setup'' tool is highly recommended as you set up your system as it will not only indicate what is wrong, but will also provide useful instructions on what to do next to correct the issue.

== Installation and Setup ==

NOTE: After NST 26 was release, the openvas packages were updated to version 9. The steps below assume that unix sockets (not TCP connections) will be preferred when communicating between the scanner (openvas-scanner service), manager (openvas-manager) and web interface (gsa-service). The main TCP port open should be 9443 after setup for the web interface. In order to accomplish this you will need to edit (comment) several lines in the /etc/sysconfig/openvas-* files.

Log into a terminal as ''root'' and make sure the following packages are installed (alien, nsis and texlive-collection-latexextra are optional, but you will be missing some functionality if you do not include them):

dnf install openvas-libraries openvas-scanner openvas-manager openvas-cli openvas-gsa gnutls-utils redis alien nsis texlive-collection-latexextra

Edit the file /etc/sysconfig/openvas-manager and comment out the TCP connection to the scanner so that unix sockets are used by the manager when talking to the scanner:

#Manager listens on given address - by default manager listens on all addresses
MANAGER_LISTEN=--listen=127.0.0.1

#Manager listens on given port - by default 9390
MANAGER_PORT=--port=9390

#Contact scanner on given address
#SCANNER_LISTEN=--scanner-host=127.0.0.1

#Scanner listens on given port - by default 9391
#SCANNER_PORT=--scanner-port=9391

Edit the file /etc/sysconfig/openvas-gsa and make sure it looks similar to the following:

#GSA listens on given address - by default GSA listens on all addresses
#GSA_LISTEN=--listen=127.0.0.1

#GSA listens on given port - by default 443
GSA_PORT=--port=9443

#Contact manager on given address
MANAGER_LISTEN=--mlisten=127.0.0.1

#Manager listens on given port - by default 9390
MANAGER_PORT=--mport=9390

#GNUTLSSTRING
GNUTLSSTRING=--gnutls-priorities=SECURE128:-AES-128-CBC:-CAMELLIA-128-CBC:-VERS-SSL3.0:-VERS-TLS1.0

Add a symlink so that the manager will be able to find certificates when accepting connections on port 9390 (you only need to do this if the symbolic link is missing):

ln -s /var/lib/openvas /etc/pki

Use the openvas-check-setup command as a diagnostic and guide during the installation process. We will be running this command a lot and it will report an ERROR until we complete the setup!

openvas-check-setup --v9

Edit the ''/etc/redis.conf'' file and make certain that the following two lines are uncommented (NOTE: We are not entirely certain that this step is required):

unixsocket /tmp/redis.sock
unixsocketperm 700

Start and enable the ''redis'' service (restart if already running and you modified the configuration file):

systemctl restart redis.service
systemctl enable redis.service # To enable at boot
openvas-check-setup --v9

Update the security checks using the ''greenbone'' tools:

greenbone-nvt-sync
greenbone-scapdata-sync
greenbone-certdata-sync
openvas-check-setup --v9

Start and enable the OpenVAS scanner service to initialize NVT cache:

systemctl start openvas-scanner.service
systemctl enable openvas-scanner.service # To enable at boot
# NOTE: It takes a LONG TIME for the openvas-scanner.service to start
# up the first time dues to loading of a large number of NVTs.
# You can do a status request to get an idea of how far along it is in
# the process (look for the Reload ETA).

systemctl status openvas-scanner.service
● openvas-scanner.service - OpenVAS Scanner
Loaded: loaded (/usr/lib/systemd/system/openvas-scanner.service; disabled; v>
Active: active (running) since Sun 2018-05-27 10:38:52 EDT; 24s ago
Process: 4112 ExecStart=/usr/sbin/openvassd $SCANNER_SOCKET $SCANNER_MODE $SC>
Main PID: 4113 (openvassd)
Tasks: 2 (limit: 4915)
Memory: 30.6M
CGroup: /system.slice/openvas-scanner.service
├─4113 openvassd: Reloaded 3650 of 45101 NVTs (8% / ETA: 04:32)
└─4114 openvassd (Loading Handler)

# Eventually the NVTs to should load and you can check where you
# are at in the setup process.
openvas-check-setup --v9

Rebuild the openvas manager database:

install -D -d -m 755 /var/lib/openvas/openvasmd/gnupg
rm -f /var/lib/openvas/mgr/tasks.db
openvasmd -f -v --rebuild
openvas-check-setup --v9

Create a user account (''admin'' in this example). Make sure you remember or copy/paste the password that is displayed (it will be a long string of random characters). Or, set it to a preferred password

openvasmd --create-user=admin --role=Admin
# To change the password after creation, use:
openvasmd --user=admin --new-password=PASSWORD
openvas-check-setup --v9

Update the certificates:

openvas-manage-certs -a
openvas-check-setup --v9

Start and enable the OpenVAS manager service:

systemctl start openvas-manager.service
systemctl enable openvas-manager.service # To enable at boot
openvas-check-setup --v9

Start and enable the Greenbone Security Assistant (GSA) service:

systemctl start openvas-gsa.service
systemctl enable openvas-gsa.service # To enable at boot
openvas-check-setup --v9

== Accessing OpenVAS on an NST Probe ==

You should now be able to access the Greenbone Security Assistant at https://127.0.0.1:9443 (you can substitute the IP address of your NST system for the ''127.0.0.1'' if accessing remotely).

You should be able to log in as ''admin'' using the initially generated password. After logging in, select ''User'' under the ''Administration'' menu and update your password (if desired).

You should also be able to verify that the OpenVAS Command Line Interface (CLI) by running:

omp --ping
omp -p 9390 --username=admin --password=YOUR_PASSWORD --xml="<help/>"
...

Refer to the http://openvas.org/ web site for instructions on using OpenVAS and the Greenbone Security Assistant.

= '''NST 22 Setup''' =

== Installation and Setup ==

Log into a terminal as ''root'' and make sure the following packages are installed:

dnf install openvas-libraries openvas-scanner openvas-manager openvas-cli openvas-gsa gnutls-utils

Update the security checks using the ''openvas-nvt-sync'' tool:

openvas-nvt-sync

Edit the ''/etc/redis.conf'' file and make certain that the following two lines are uncommented (NOTE: We are not entirely certain that this step is required):

unixsocket /tmp/redis.sock
unixsocketperm 777

Start and enable the ''redis'' service (restart if already running and you modified the configuration file):

systemctl restart redis.service
systemctl enable redis.service

Start and enable the OpenVAS scanner and manager services:

systemctl start openvas-scanner.service
systemctl enable openvas-scanner.service
systemctl start openvas-manager.service
systemctl enable openvas-manager.service

Create a client certificate:

openvas-mkcert-client -n -i

To test the connection, run (you can press ''Control-D'' to end the connection):

gnutls-cli --insecure -p 9391 127.0.0.1 --x509keyfile=/etc/pki/openvas/private/CA/clientkey.pem --x509certfile=/etc/pki/openvas/CA/clientcert.pem

Instruct OpenVAS to rebuild its database:

openvasmd --rebuild

Create a user account (''admin'' in this example). Make sure you remember or copy/paste the password that is displayed (it will be a long string of random characters).

openvasmd --create-user=admin

Restart the OpenVAS manager service:

systemctl restart openvas-manager.service

Start and enable the Greenbone Security Assistant (GSA) service:

systemctl start openvas-gsa.service
systemctl enable openvas-gsa.service

== Accessing OpenVAS on an NST Probe ==

You should now be able to access the Greenbone Security Assistant at https://127.0.0.1:9443 (you can substitute the IP address of your NST system for the ''127.0.0.1'' if accessing remotely).

You should be able to log in as ''admin'' using the initially generated password. After logging in, select ''User'' under the ''Administration'' menu and update your password.

From the main page, you can perform a quick scan on the NST system itself by entering ''127.0.0.1'' and pressing the ''Start Scan'' button:

[[Image:openvas-quickscan.png]]

When the scan completes it may report a few medium severity issues related to the ''openvasmd'' process on port 9390.

You should also be able to verify that the OpenVAS Command Line Interface (CLI) by running:

omp --ping
omp -p 9390 --username=admin --password=YOUR_PASSWORD --xml="<help/>"
...

Refer to the http://www.openvas.com/ web site for instructions on using OpenVAS and the Greenbone Security Assistant.

= '''NST 16 and NST 18 Setup''' =

<div class="centerBlock"><div class="noteMessage">'''NST 2.16.0 - Preliminary Notes: '''Starting with Fedora 16, getting '''OpenVAS''' working with the '''Greenbone Security Assistant''' Desktop and Web interface has been a challenge. We are currently in the process of trying to figure out how to get it working. Currently only the '''openvas-client''' is available for '''OpenVAS''' control.</div></div>

== '''Steps To Get OpenVAS Started With NST 16 and NST 18''' ==
* Add an OpenVAS client user (e.g., 'root') (Respond to all command prompts):

[root@dhcp132 ~]# '''openvas-adduser'''

* To synchronize OpenVAS security checks, use the ''openvas-nvt-sync'' command:

[root@dhcp132 ~]# '''openvas-nvt-sync'''

* Start the OpenVAS Scanner service. This will take minutes to hours to complete (at least the first time). If it takes too long, a failure will be reported, but the process will continue to run and parse the ''.nasl'' files out of the ''/var/lib/openvas/plugins'' directory. If you get hit with the timeout situtation, you can use the '''top''' command to monitor the '''openvassd'' process :

[root@dhcp132 ~]# '''systemctl start openvas-scanner.service'''

* The OpenVAS Scanner service may take many minutes to start when initially loading all of the ''.nasl'' plugins found under the ''/var/lib/openvas/plugins'' directory. It may take so long that you may see a failure message reported in the previous step due to a time out. If this occurs, you can use the '''top''' command to monitor the load of the '''openvassd''' process and wait for the load the drop. Here's an example of a high load by the '''openvassd''' process:

top - 07:30:17 up 18:33, 3 users, load average: 1.50, 1.47, 1.25
Tasks: 142 total, 2 running, 140 sleeping, 0 stopped, 0 zombie
Cpu0 : 7.6%us, 20.9%sy, 0.0%ni, 0.0%id, 0.8%wa, 68.9%hi, 1.8%si, 0.0%st
Mem: 1027908k total, 897168k used, 130740k free, 119148k buffers
Swap: 2064380k total, 612k used, 2063768k free, 480452k cached

PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
27120 root 20 0 43092 35m 1832 S 17.9 3.6 2:04.78 openvassd
1 root 20 0 5688 3464 1952 S 0.5 0.3 0:08.17 systemd
306 root 20 0 0 0 0 S 0.1 0.0 0:00.88 jbd2/dm-1-8
4239 root 20 0 0 0 0 S 0.1 0.0 0:16.80 kworker/0:2
4262 root 20 0 57420 19m 9208 S 0.1 1.9 0:34.68 Xorg

* Before starting the openvas-manager (openvasmd) service, you need to initialize (rebuild) it's database the first time you set up your system. Run the following command to rebuild the database:

[root@dhcp132 ~]# '''openvasmd --rebuild'''

* Start the OpenVAS Manager service:

[root@dhcp132 ~]# '''systemctl start openvas-manager.service'''

* At this point both the OpenVAS Scanner (openvassd:9391) & Manager (openvasmd:9390) service should be started:

[root@dhcp132 ~]# '''netstat -tunap'''
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
tcp 0 0 0.0.0.0:5900 0.0.0.0:* LISTEN 2024/vino-server
tcp 0 0 0.0.0.0:9390 0.0.0.0:* LISTEN 27395/openvasmd
tcp 0 0 0.0.0.0:9391 0.0.0.0:* LISTEN 25093/openvassd
tcp 0 0 127.0.0.1:80 0.0.0.0:* LISTEN 1391/httpd
tcp 0 0 0.0.0.0:22 0.0.0.0:* LISTEN 1378/sshd
tcp 0 0 0.0.0.0:3001 0.0.0.0:* LISTEN 1382/ntop
tcp 0 0 127.0.0.1:6010 0.0.0.0:* LISTEN 11949/sshd
tcp 0 0 0.0.0.0:443 0.0.0.0:* LISTEN 1391/httpd
tcp 0 0 10.222.222.10:22 10.222.222.18:49240 ESTABLISHED 11949/sshd
tcp 0 0 10.222.222.10:5900 10.222.222.18:53555 ESTABLISHED 2024/vino-server
tcp 0 0 :::5900 :::* LISTEN 2024/vino-server
tcp 0 0 :::22 :::* LISTEN 1378/sshd
tcp 0 0 ::1:6010 :::* LISTEN 11949/sshd
udp 0 0 0.0.0.0:123 0.0.0.0:* 981/chronyd
udp 0 0 0.0.0.0:323 0.0.0.0:* 981/chronyd
udp 0 0 :::123 :::* 981/chronyd
udp 0 0 :::323 :::* 981/chronyd
[root@cayenne ~]# '''systemctl status openvas-scanner.service'''
openvas-scanner.service - OpenVAS Scanner
Loaded: loaded (/usr/lib/systemd/system/openvas-scanner.service; disabled)
Active: active (running) since Fri 2013-05-10 20:43:42 EDT; 10h ago
Main PID: 19509 (openvassd)
CGroup: name=systemd:/system/openvas-scanner.service
├─10466 openvassd: serving 127.0.0.1
├─10486 openvassd: serving 127.0.0.1
└─19509 openvassd: waiting for incoming connections

May 10 20:41:53 cayenne openvassd[19439]: [120B blob data]
May 10 20:42:03 cayenne openvassd[19439]: [120B blob data]
May 10 20:42:14 cayenne openvassd[19439]: [120B blob data]
May 10 20:42:26 cayenne openvassd[19439]: [120B blob data]
May 10 20:42:40 cayenne openvassd[19439]: [120B blob data]
May 10 20:42:54 cayenne openvassd[19439]: [120B blob data]
May 10 20:43:10 cayenne openvassd[19439]: [120B blob data]
May 10 20:43:28 cayenne openvassd[19439]: [120B blob data]
May 10 20:43:42 cayenne openvassd[19439]: [120B blob data]
May 10 20:43:42 cayenne systemd[1]: Started OpenVAS Scanner.
[root@cayenne ~]# '''systemctl status openvas-manager.service'''
openvas-manager.service - OpenVAS Manager
Loaded: loaded (/usr/lib/systemd/system/openvas-manager.service; disabled)
Active: active (running) since Fri 2013-05-10 20:54:37 EDT; 10h ago
Main PID: 19571 (openvasmd)
CGroup: name=systemd:/system/openvas-manager.service
└─19571 /usr/sbin/openvasmd --port=9390 --slisten=127.0.0.1 --sport=9391 --otp

May 10 20:54:37 cayenne systemd[1]: Starting OpenVAS Manager...
May 10 20:54:37 cayenne systemd[1]: Started OpenVAS Manager.
[root@cayenne ~]#

* Finally, from a Gnome Desktop start up the '''OpenVAS''' client ('''/usr/bin/openvas-client''') and login as the user added in the first step:
'''Applications => System Tools => OpenVAS Client'''

'''NOTE''': It takes a long time to load the initial rules when using ''openvas-client''. The application may appear to hang and you may need to be patient for a few minutes as rules are loaded.

'''NOTE2''': When ''openvas-client'' disconnects and exits, the ''openvassd'' process that was forked to serve it may not cleanly exit and consume 100% of a CPU. You can use the '''top''' command to identify and kill this process should it occur.

== Accessing OpenVAS on an NST Probe ==

* From the NST WUI menu system (Web-Based Interface - WUI): '''Security''' => '''Active Scanners''' => '''Greenbone Security WUI (OpenVAS)'''

* From the Gnome or Fluxbox Desktop (X Window-Based Interface - GUI): '''Greenbone Security Desktop Tool'''

= '''Steps To Get OpenVAS Started With NST 15''' =
== Command Line Setup ==

This section outlines the general procedure for setting up OpenVAS on a NST v2.15.0 system using the command line.



=== First Download/Update the OpenVAS Plugins ===

To install (or update if you've already installed the plugins at some point in the past), use the ''openvas-nvt-sync'' command. For example:

[root@dhcp132 ~]# openvas-nvt-sync

... Lots of output as rules are updated ...

[root@dhcp132 ~]#

WARNING: Due not try this on a Live boot of the NST, as it writes a large amount of data to disk (which consumes RAM in a live boot).

The plugins for OpenVAS will be installed under the ''/var/lib/openvas/plugins'' directory. This directory won't exist until the initial plugins are installed using the ''openvas-nvt-sync'' command shown above. The following command shows how to get a count of the currently available plugins:

[root@dhcp132 ~]# ls /var/lib/openvas/plugins | wc -l
42962
[root@dhcp132 ~]#

=== Next Start The openvas-scanner Service ===

Starting the openvas-scanner (openvassd) service takes a long time. This occurs due to the loading and processing of all of the rules. When the service is started, it reads through all of the ASCII plugins and creates cached versions under the ''/var/cache/openvas'' directory. The first time you try and start the service, ''systemctl'' may time out and report that the service failed to start even though the ''openvassd'' process is still running and parsing rules. For example:

[root@cayenne ~]# systemctl start openvas-scanner.service
Job failed. See system logs and 'systemctl status' for details.
[root@cayenne ~]# ps -fC openvassd
UID PID PPID C STIME TTY TIME CMD
root 3813 3812 48 13:30 ? 00:02:34 openvassd -q --port=9391
[root@cayenne ~]#

It takes a very long time for the initial loading and processing of the plugins. You can try to peek at what plugins are currently being loaded (to assure yourself that progress is being made) using the ''lsof'' command (this doesn't always work and depends a bit on the start of the ''openvassd'' process):

[root@cayenne ~]# lsof | grep /var/lib/openvas/plugins
openvassd 12858 root cwd 4r REG 253,1 2635 21050 /var/lib/openvas/plugins/plugins/gb_MDaemon_39857.nasl
[root@cayenne ~]#

If you run the ''top'' command while the ''openvassd'' is processing the plugins, you should see the ''openvassd'' consuming a substantial amount of CPU.

Eventually the ''openvassd'' process will complete it's loading phase and enter into a state where it is ready to accept incoming connections. You can use the ''ps'' command to check for this.

[root@dcayenne ~]# ps -fC openvassd
UID PID PPID C STIME TTY TIME CMD
root 24529 1 0 07:13 ? 00:00:00 openvassd: waiting for incoming
[root@dcayenne ~]#

The ''systemctl'' command can also be used to verify that the ''openvassd'' process is ready for incoming connections:

[root@cayenne ~]# systemctl status openvas-scanner.service
openvas-scanner.service - LSB: start|stop|status|restart|condrestart|reloadplugins OpenVAS Scanner
Loaded: loaded (/etc/rc.d/init.d/openvas-scanner)
Active: failed since Wed, 15 Jun 2011 07:10:23 -0400; 7min ago
Process: 2164 ExecStart=/etc/rc.d/init.d/openvas-scanner start (code=killed, signal=TERM)
CGroup: name=systemd:/system/openvas-scanner.service
└ 24529 openvassd: waiting for incoming connections
[root@cayenne ~]#

You may notice that ''systemctl'' reports the service in a ''failed'' state even though the ''openvassd'' daemon is running and accepting connections. You should be able to clear this ''failed'' state indicator by restarting the service.

[root@cayenne ~]# systemctl restart openvas-scanner.service
[root@cayenne ~]# systemctl status openvas-scanner.service
openvas-scanner.service - LSB: start|stop|status|restart|condrestart|reloadplugins OpenVAS Scanner
Loaded: loaded (/etc/rc.d/init.d/openvas-scanner)
Active: active (running) since Sat, 16 Jul 2011 13:44:52 -0400; 1min 6s ago
Process: 27198 ExecStart=/etc/rc.d/init.d/openvas-scanner start (code=exited, status=0/SUCCESS)
Main PID: 27193 (openvassd)
CGroup: name=systemd:/system/openvas-scanner.service
└ 27193 openvassd: waiting for incoming connections
[root@cayenne ~]#
[root@cayenne ~]#

To enable the ''openvas-scanner'' (openvassd) service at boot time, run the following command:

[root@cayenne ~]# systemctl enable openvas-scanner.service
openvas-scanner.service is not a native service, redirecting to /sbin/chkconfig.
Executing /sbin/chkconfig openvas-scanner on
[root@cayenne ~]#

=== Next Start The openvas-manager Service ===

Before starting the openvas-manager (openvasmd) service, you need to initialize (rebuild) it's database the first time you set up your system. Run the following command to rebuild the database:

[root@cayenne ~]# openvasmd --rebuild
[root@cayenne ~]#

Once the database has been setup, you can start the service in the following manner:

[root@cayenne ~]# systemctl start openvas-manager.service
[root@cayenne ~]# systemctl status openvas-manager.service
openvas-manager.service - LSB: start|stop|status|restart|condrestart OpenVAS Manager
Loaded: loaded (/etc/rc.d/init.d/openvas-manager)
Active: active (running) since Sat, 16 Jul 2011 13:56:41 -0400; 5s ago
Process: 27445 ExecStart=/etc/rc.d/init.d/openvas-manager start (code=exited, status=0/SUCCESS)
Main PID: 27450 (openvasmd)
CGroup: name=systemd:/system/openvas-manager.service
└ 27450 openvasmd --port=9390 --slisten=127.0.0.1 --sport=...
[root@cayenne ~]#

To enable the ''openvas-manager'' (openvasmd) service at boot time, run the following command:

[root@cayenne ~]# systemctl enable openvas-manager.service
openvas-manager.service is not a native service, redirecting to /sbin/chkconfig.
Executing /sbin/chkconfig openvas-manager on
[root@cayenne ~]#

=== Next Start The openvas-administrator Service ===

Before starting the openvas-administrator (openvasad) service, you need to add a administrative user. The following demonstrates how to add a ''root'' user (you can choose any name you prefer):

[root@cayenne ~]# openvasad -c add_user -n root --role=Admin
Enter password:
ad main:MESSAGE:23822:2011-06-15 07h54.32 EDT: No rules file provided, the new user will have no restrictions.
ad main:MESSAGE:23822:2011-06-15 07h54.32 EDT: User root has been successfully created.
[root@cayenne ~]#

Once a administrative user has been added, you should be able to start the service as shown below

[root@cayenne ~]# systemctl start openvas-administrator.service
[root@cayenne ~]# systemctl status openvas-administrator.service
openvas-administrator.service - LSB: start|stop|status|restart|condrestart OpenVAS Manager
Loaded: loaded (/etc/rc.d/init.d/openvas-administrator)
Active: active (running) since Sat, 16 Jul 2011 13:59:17 -0400; 3s ago
Process: 27475 ExecStart=/etc/rc.d/init.d/openvas-administrator start (code=exited, status=0/SUCCESS)
Main PID: 27480 (openvasad)
CGroup: name=systemd:/system/openvas-administrator.service
└ 27480 openvasad --port=9393
[root@cayenne ~]#

To enable the ''openvas-administrator'' (openvasad) service at boot time, run the following command:

[root@cayenne ~]# systemctl enable openvas-administrator.service
openvas-administrator.service is not a native service, redirecting to /sbin/chkconfig.
Executing /sbin/chkconfig openvas-administrator on
[root@cayenne ~]#

=== Next Start The gsad Service ===

Once the OpenVAS services are set up and running, you should be able to start the Greenbone Security Assistant service as follows:

[root@cayenne ~]# systemctl start gsad.service
[root@cayenne ~]# systemctl status gsad.service
gsad.service - LSB: This starts and stops the Greenbone Security Assistant.
Loaded: loaded (/etc/rc.d/init.d/gsad)
Active: active (running) since Sat, 16 Jul 2011 14:14:30 -0400; 4s ago
Process: 27880 ExecStart=/etc/rc.d/init.d/gsad start (code=exited, status=0/SUCCESS)
Main PID: 27886 (gsad)
CGroup: name=systemd:/system/gsad.service
└ 27886 /usr/sbin/gsad --port=9392 --alisten=127.0.0.1 --a...
[root@cayenne ~]#

To enable the ''gsad'' service at boot time, run the following command:

[root@cayenne ~]# systemctl enable gsad.service
gsad.service is not a native service, redirecting to /sbin/chkconfig.
Executing /sbin/chkconfig gsad on
[root@cayenne ~]#

=== Finally Verify Your Setup Using openvas-check-setup ===

After you have all of the services set up and running, you can use the ''openvas-check-setup'' command to perform a sanity check on your system to verify that it has been setup correctly.

[root@cayenne ~]# openvas-check-setup

... Lots of output as various checks are performed.
If not all OK, then a SUGGESTION should appear ...

It seems like your OpenVAS-4 installation is OK.

If you think it is not OK, please report your observation
and help us to improve this check routine:
http://lists.wald.intevation.org/mailman/listinfo/openvas-discuss
Please attach the log-file (/tmp/openvas-check-setup.log) to help us analyze the problem.

[root@cayenne ~]#

Transfer to SourceForge

2019-07-16T16:04:49Z

Paul Blankenbaker:

= Tweak Release Notes =

You should copy the release notes to a file named ''README.txt'', review and ''tweak'' them prior to uploading the files. For example:

[nst@nst24-repo repo]$ cp nst-24-7977/release-notes-24-7977.txt nst-24-7977/README.txt
[nst@nst24-repo repo]$ emacs -nw nst-24-7977/README.txt

= FTP to SourceForge =

At this point you can start transferring files to SourceForge. The '''make -C yum sftp-sf''' can be used to simplify this task (NOTE: It defaults to Nautilus if the DISPLAY variable is set, unset DISPLAY to remain on the command line).

[nst@nst24-repo repo]$ (unset DISPLAY; make -C yum sftp-sf SFUSER=USERNAME)
make: Entering directory '/home/nst/repo/yum'
if [ -z "" ]; then \
sftp USERNAME,nst@frs.sourceforge.net:/home/frs/project/n/ns/nst/; \
else \
nautilus ssh://USERNAME,nst@frs.sourceforge.net/home/frs/project/n/ns/nst/; \
fi
Connected to frs.sourceforge.net.
Changing to: /home/frs/project/n/ns/nst/
sftp> mkdir "NST/NST 24-7977"
sftp> ls NST
NST/NST 20-6535 NST/NST 22-7248 NST/NST 22-7334 NST/NST 24-7977
sftp> cd "NST/NST 24-7977"
sftp> lcd ../nst-24-7977
sftp> lls
nst-24-7977.tar.gz README.txt
nst-24-7977.x86_64.iso release-notes-24-7977.txt
sftp> put README.txt
Uploading README.txt to /home/pfs/project/n/ns/nst/NST/NST 24-7977/README.txt
README.txt 100% 1150 1.1KB/s 00:01
sftp> put nst-24-7977.tar.gz
Uploading nst-24-7977.tar.gz to /home/pfs/project/n/ns/nst/NST/NST 24-7977/nst-24-7977.tar
sftp> put nst-24-7977.x86_64.iso
Uploading nst-24-7977.x86_64.iso to /home/pfs/project/n/ns/nst/NST/NST 24-7977/nst-24-7977.x86_64.iso
sftp> exit
[nst@nst24-repo repo]$

Tag Source For Release

2019-07-16T15:57:29Z

Paul Blankenbaker:

Use the ''svn cp'' command to create a branch of the files used for the release (a copy of "repo"). For example:

[nst@repo repo]$ VER=30
[nst@repo repo]$ SVNVER=11210
[nst@repo repo]$ svn cp -m "Creating copy of source for ${VER}-${SVNVER} release" ${SVNROOT}/repo/${VER} ${SVNROOT}/releases/${VER}-${SVNVER}

... output from branch creation ...

[nst@repo repo]$

Boot Release

2019-07-16T14:19:16Z

Paul Blankenbaker:

It is recommended that you burn and boot from any ISO images PRIOR to uploading them to SourceForge. If you've followed all of the steps in the release guide, they should work flawlessly.

== Full NST Live Distribution ==

* Verify that the NST Live distribution boots cleanly.
* Verify that you can log in.
* Verify that you can access the system using ''ssh'' and ''https'' after running the '''nstpasswd''' command to set the system passwords.
* Verify that you can install the distribution to hard disk.
* Verify that you can boot off the hard disk installation.
* Reboot the hard disk system.
* Verify that you can access the system using ''ssh'' and ''https'' after running the '''nstpasswd''' command to set the system passwords.



== RPM Verify ==

After booting, run the following command to review verification issues in RPM packages:

[root@nst30-repo repo30]# make HOST=192.168.0.9 rpm-verify

... Review results of the rpm-verify output ...

[root@nst30-repo repo30]#

Then for a live check, run:

[root@nst30-repo repo30]# make rpm-verify-diff-live

... NOTE: The include/make/rpm-verify.expect.live.txt file is likely out of data
don't panic if there are any issues flagged ...

[root@nst30-repo repo30]#

Then for a hard disk install, run:

[root@nst30-repo repo30]# make rpm-verify-diff-hd

... NOTE: The include/make/rpm-verify.expect.hd.txt file is likely out of data
don't panic if there are any issues flagged ...

[root@nst30-repo repo30]#

== Probe Check ==

After booting the full NST Live distribution, do to your development machine and run: ''make probe-check HOST=IP'' against the newly booted NST probe. Review the resulting log file to verify that the test results look reasonable.

NOTE: Make sure you install your ssh keys (run '''ssh-auth-keys --hosts IP --users root''') before running the '''make''' command.

[root@nst30-repo repo30]# make probe-check HOST=192.168.0.9

... Lot's of output as various checks and tests are made ..

[root@nst30-repo repo30]# less -R probe-check.log

... Review results of the probe-check output ...

[root@nst30-repo repo30]#

Do a Sanity Check

2019-07-08T18:43:25Z

Paul Blankenbaker: Updated expected systemctl service list

Prior to creating a release, one should perform the following sanity checks.

Note: In order to perform all of the sanity checks, you will need BOTH your NST development system and a running NST probe.

== Commit ==

You should do a commit to ensure that you do not have any outstanding modifications.

svn commit

== Build Yum Repository ==

Run the following from the top level directory to make certain that you can build and update all the RPM files that make up the NST repository.

dnf clean all
make repo-build

== Check Enabled Services ==

Make sure you boot a recent ISO image and verify that the expected services are enabled at boot time. Be aware that the '''sshd''' and '''httpd''' services will not be enabled or running until the '''nstpasswd''' command is run.

[root@localhost ~]# chkconfig --list | grep 3:on

Note: This output shows SysV services only and does not include native
systemd services. SysV configuration data might be overridden by native
systemd configuration.

If you want to list systemd services use 'systemctl list-unit-files'.
To see services enabled on particular target use
'systemctl list-dependencies [target]'.

livesys 0:off 1:off 2:off 3:on 4:on 5:on 6:off
livesys-late 0:off 1:off 2:off 3:on 4:on 5:on 6:off
[root@localhost ~]#

As noted in the output, the above doesn't show information about native systemd services. To view those services as well, run the following command and review the output produced.NOTE: The output shown below was produced after booting the NST ISO in VirtualBox and selecting the default ''Graphical Desktop'' target.

[root@localhost ~]# systemctl list-unit-files | grep enabled | grep service | sort
abrt-journal-core.service enabled
abrt-oops.service enabled
abrt-vmcore.service enabled
abrt-xorg.service enabled
accounts-daemon.service enabled
autovt@.service enabled
dbus-broker.service enabled
dbus-daemon.service enabled
dbus-org.freedesktop.ModemManager1.service enabled
dbus-org.freedesktop.nm-dispatcher.service enabled
dbus-org.freedesktop.timedate1.service enabled
dbus.service enabled
dbxtool.service enabled
display-manager.service enabled
dkms.service enabled
dmraid-activation.service enabled
getty@.service enabled
import-state.service enabled
irqbalance.service enabled
lightdm.service enabled
lvm2-monitor.service enabled
mcelog.service enabled
messagebus.service enabled
ModemManager.service enabled
multipathd.service enabled
NetworkManager-dispatcher.service enabled
NetworkManager.service enabled
NetworkManager-wait-online.service enabled
nstboot.service enabled
rngd.service enabled
rsyslog.service enabled
rtkit-daemon.service enabled
selinux-autorelabel-mark.service enabled
smartd.service enabled
sssd.service enabled
timedatex.service enabled
udisks2.service enabled
vboxservice.service enabled
vgauthd.service enabled
vmtoolsd-init.service enabled
vmtoolsd.service enabled
[root@localhost ~]#

You might only see the ''vboxservice.service'' entry if you are running under VirtualBox.

== Verify That Documentation Builds ==

Make sure the ''docs'' directory builds. This is required to update the on-line version of the man pages for the release:

[root@dev repo]# cd docs
[root@dev docs]# make

== Run Automated Tests ==

Run the following from the top level to perform numerous checks on the running NST probe with the IP address specified.

make probe-check HOST=IP

There will be a LOT of output produced. A copy of the output will be saved to the file: "probe-check.log" which may be viewed using the command: "less -R probe-check.log". Make sure the file looks clean (or like you would expect). Make sure you aren't tempted to skip this step. We thought we were OK and skipped this step during the 1.8.1 release and ended up delivering a ISO image with a broken sym-link.

Subversion Notes

2019-07-03T10:18:49Z

Paul Blankenbaker: Updated for the new svn relocate command

We switched from using CVS to Subversion as our source control mechanism in mid October 2009.

* We did not try to import all of the CVS history.
* The initial import includes all of the 2.11.0 release source plus the updated source code since the release (the state of CVS on 2009-10-14).
* We left the CVS repository alone (in case we ever wanted to refer back for older history).

= Preparing Development Machine =

As a developer, the following things must be done to your development machine before you will be able to check out, build and commit changes to the NST source code.

== Set SVNROOT ==

You need to set the ''SVNROOT'' variable. Add the following to your '''~/.bashrc''' or '''~/.bash_profile''' configuration file:

export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst

After the ''SVNROOT'' variable is set, you should be able to run Subversion commands. For example the following shows the directories under ''SVNROOT''.

[pkb@sprint ~]$ export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst
[pkb@sprint ~]$ svn ls ${SVNROOT}
trunk/
[pkb@sprint ~]$

== gnome-keyring ==

Subversion might complain about needing to store passwords in a ''unencrypted'' form. To prevent this, we need to figure out how to enable the ''gnome-keyring'' add-on. To do this, edit the file '''~/.subversion/config''' and search on the string ''password-stores''. Most likely this will be commented out in your current configuration file. I updated mine to the following:

password-stores = gnome-keyring

However, this was not enough to prevent me from being prompted each time. I then added the following package:

yum install subversion-gnome

We will see if this permits us to store the password or not (you may need to be logged into a GNOME desktop in order to make use of the gnome-keyring feature).

= Directory Structure =

Currently the directory structure under Subversion is fairly straight forward. We use ''trunk'' as the current working area (this is what most developers will be checking out from and committing to). When we have a release, we will copy ''trunk'' to the release number. For example, to create the ''2.13.0'' release, we would run the following Subversion command:

svn copy ${SVNROOT}/trunk ${SVNROOT}/releases/2.13.0

We would also run the following command for maintenance updates to the ''2.13.0'' release:

svn copy ${SVNROOT}/trunk ${SVNROOT}/maintenance/2.13.0

= Subversion Commands =

Use the following to get the list of available subversion commands:

svn help

To get more information about a specific Subversion command (like ''ls''), run:

svn help ls

== Checking Out Code ==

To make the initial checkout of the current source code into a sub-directory named ''nst'', you can use the following Subversion command:

svn co ${SVNROOT}/trunk nst

== Committing Code ==

You use the ''commit'' subversion command when you want to commit changes to the source code.

When you first run ''commit'', it may prompt you for the password for the incorrect user ID. If this happens, press the ''Enter'' key without specifying a password. This should allow you enter your SourceForge user ID followed by your SourceForge password when committing changes. For example:

[root@fedora11 nightly]# svn commit
Authentication realm: <https://nst.svn.sourceforge.net:443> SourceForge Subversion area
Password for 'root':
Authentication realm: <https://nst.svn.sourceforge.net:443> SourceForge Subversion area
Username: SOURCEFORGE_LOGIN_ID
Password for 'SOURCEFORGE_LOGIN_ID':
Sending nightly/nightly-build.bash
Sending nightly/nightly2html.xsl
Sending nightly/nightly2txt.xsl
Transmitting file data ...-----------------------------------------------------------------------
ATTENTION! Your password for authentication realm:

<https://nst.svn.sourceforge.net:443> SourceForge Subversion area

can only be stored to disk unencrypted! You are advised to configure
your system so that Subversion can store passwords encrypted, if
possible. See the documentation for details.

You can avoid future appearances of this warning by setting the value
of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
'/root/.subversion/servers'.
-----------------------------------------------------------------------
Store password unencrypted (yes/no)? no

Committed revision 4.
[root@fedora11 nightly]#

== Status ==

The Subversion status command is very handy at showing not only what files you've modified, but also (when including the ''-u'' option) handy at showing what files have changed in the repository:

svn status -u

For help about the output of ''svn status'', run:

svn help status | less

== Revert ==

If you've made modifications to a file which you want to discard, use the ''revert'' command to restore the original version:

svn revert FILENAME

To revert back to a previous revision use the '''merge''' option. The follow example reverts back to the '''3986''' revision from the '''3987''' revision for file: "'''bwmonitor.js'''". After the revert changes are applied you will need to '''commit'''. Use the [http://nst.svn.sourceforge.net/viewvc/nst/ Subversion Browser] to assit in finding your revision numbers.

svn merge -r 3987:3986 bwmonitor.js

== Revert Commit, Undo Commit, Reverse Merge ==

If you've committed modifications to a file accidentally it is a bit tricky to ''undo'' the commit. To get back an older version you need to perform something called a reverse merge. This is done by running the ''svn merge -r BAD:GOOD SOURCE'' command. Where BAD is typically the current revision ID of the source you want to revert, GOOD is the revision ID of the good code you want to restore and is typically 1 less than the value of BAD. SOURCE is typically the name of the file or directory you want to undo the commit on.

For example, we can used the following command to determine the last changed revision of the files under the current directory:

[pkb@refritos server]$ svn info . | grep Rev:
Last Changed Rev: 10660
[pkb@refritos server]$

In this example the BAD revision ID is 10660 associated with the last commit done to this area. To restore the files to the 10659 state (the good version prior to the 10660) state, we would run the following command:

[pkb@refritos server]$ svn merge -r 10660:10659 .
--- Reverse-merging r10660 into '.':
U xrdp.cgi
--- Recording mergeinfo for reverse merge of r10660 into '.':
G .
--- Eliding mergeinfo from '.':
U .
[pkb@refritos server]$

As the ''status'' command shows, this undo only impacted one file in the directory and is not immediately reflected in the repository.

[pkb@refritos server]$ svn status
M xrdp.cgi
[pkb@refritos server]$

This allows us to inspect the undone changes. If we are happy, we can commit this version back. If we are unhappy with the results, we can revert the state of the directory and try again.

== Ignoring Files ==

Under CVS, you could edit the file '''.cvsignore''' to tell CVS to ignore certain files within the directory. Subversion has a similar, but different mechanism for ignoring files. Basically, you change to the directory where the files/directories to be ignored exist and run the following command:

svn propedit svn:ignore .

Running the above command should pull up a text editor and allow you to specify file name patterns to specify what files and directories should be ignored. Here is an example ignore list which causes Subversion to ignore any file or directory ending with the extension ''.log'' or having the name ''tmp'':

*.log
tmp

== Manage The Executable Flag On File ==
Use the following command to set the executable flag on a file (e.g., bwmonitor-ajax.php)under SVN control:

svn propset svn:executable bwmonitor-ajax.php

Use the following command to remove the executable flag on a file (e.g., bwmonitor-ajax.php)under SVN control:

svn propdel svn:executable bwmonitor-ajax.php

== Merging Changes Across Revisions ==

Our general strategy is typically to do all new work under the ''trunk'' area. However, when we move from one Fedora platform to another (like from Fedora 13 to Fedora 15), we will typically copy the ''trunk'' area to a sub-directory under the maintenance area. For example, the following shows the top level Subversion heirarchy (where you will see ''trunk'' and ''maintenance'') and the number of older maintenance areas where we have the ability to maintain older versions of the software.

[root@f13-32 ~]# svn ls $SVNROOT
maintenance/
releases/
trunk/
[root@f13-32 ~]# svn ls $SVNROOT/maintenance
2.11.0/
2.12.0/
2.13.0/
[root@f13-32 ~]#

In this situation, you may find yourself making changes to the ''trunk'' area that you would also like to apply to the ''2.13.0'' branch area. To accomplish this, use the following strategy:

* Make your updates to the ''trunk'' area.
* Commit your changes.
* Determine the range of revision numbers for your change using the [http://nst.svn.sourceforge.net/viewvc/nst/ Subversion browser].
* Use the ''svn merge'' command to merge the changes into the ''maintenance/2.13.0'' area.

Here is an example of using ''svn merge'' to merge the changes made for the 2.1.6 release of the relaycheck package from the ''trunk'' area to the ''maintenance/2.13.0'' area:

* From looking at the [http://nst.svn.sourceforge.net/viewvc/nst/maintenance/2.13.0/yum/pkgs maintenance/2.13.0/yum/pkgs/relaycheck revision number], I can see that the last revision number for the ''maintenance/2.13.0'' version was 2016 (at the time of this writing - it will change in the future).
* From looking at the [http://nst.svn.sourceforge.net/viewvc/nst/trunk/yum/pkgs trunk/yum/pkgs/relaycheck revision number], I can see that the current revision number for the ''trunk'' version of relaycheck was 2102 (at the time this article was written).
* At this point I have enough information to merge the changes with the following ''svn merge'' command:

[root@f13-32 repo]# svn info
Path: .
URL: https://nst.svn.sourceforge.net/svnroot/nst/maintenance/2.13.0
Repository Root: https://nst.svn.sourceforge.net/svnroot/nst
Repository UUID: c9574408-7c70-44fe-bb37-9fe24d5f8586
Revision: 2076
Node Kind: directory
Schedule: normal
Last Changed Author: pblankenbaker
Last Changed Rev: 2076
Last Changed Date: 2011-05-10 16:53:57 -0400 (Tue, 10 May 2011)

[root@f13-32 repo]# svn merge -r 2016:2102 $SVNROOT/trunk/yum/pkgs/relaycheck yum/pkgs/relaycheck
--- Merging r2076 through r2102 into 'yum/pkgs/relaycheck':
U yum/pkgs/relaycheck/src/relaycheck.pl
U yum/pkgs/relaycheck/pkginfo.xml
U yum/pkgs/relaycheck/relaycheck.template.spec
[root@f13-32 repo]# svn status
M yum/pkgs/relaycheck
M yum/pkgs/relaycheck/src/relaycheck.pl
M yum/pkgs/relaycheck/pkginfo.xml
M yum/pkgs/relaycheck/relaycheck.template.spec
[root@f13-32 repo]#

At this point, we should make sure the merged changes still build and then commit our changes.

NOTE: After committing the changes, the [http://nst.svn.sourceforge.net/viewvc/nst/maintenance/2.13.0/yum/pkgs maintenance/2.13.0/yum/pkgs/relaycheck revision number] changed to 2103 (at the time of this writing) which is now larger than the original 2102 revision we used for the merge.
[root@f13-32 repo]# cd yum
[root@f13-32 yum]# make relaycheck

... Omitted much of the output ...

-------------------------------------------------------------------------------
SUCCESS: Successfully installed relaycheck-1.2.6-11.nst13.noarch.rpm
-------------------------------------------------------------------------------
make[1]: Leaving directory `/root/repo/yum/pkgs/relaycheck'
[root@f13-32 yum]# svn commit

== Merging From Dev Area To The Repo Area ==

* '''Note:''' If this merge includes updates in the '''nstwui''' package: '''Have You Updated The NST WUI Release Number On The Dev Branch First?'''

The following demonstrates the current merge method to bring changes from the ''dev/20'' development branch to the ''repo/20'' area.

[root@dev20-64 ~]# cd repo
[root@dev20-64 repo]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
[root@dev20-64 repo]# svn info
Path: .
Working Copy Root Path: /root/repo
URL: https://svn.code.sf.net/p/nst/code/repo/20
Relative URL: ^/repo/20
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 6545
Node Kind: directory
Schedule: normal
Last Changed Author: rwhalb
Last Changed Rev: 6545
Last Changed Date: 2015-02-14 08:44:42 -0500 (Sat, 14 Feb 2015)

[root@dev20-64 repo]# svn update; svn merge https://svn.code.sf.net/p/nst/code/dev/20 .
At revision 6594.
--- Merging r6545 through r6594 into '.':
U include/javascript/core/NstSelect.js
U include/javascript/core/NstRuler.js

...

U yum/pkgs/putty-win32
--- Recording mergeinfo for merge of r6545 through r6594 into '.':
U .
--- Recording mergeinfo for merge of r6545 through r6594 into 'yum/pkgs/putty-win32':
G yum/pkgs/putty-win32
[root@dev20-64 repo]# svn commit -m "Merging up to 6545 from dev/20"
... output from commit ...
[root@dev20-64 repo]#

This is the old method used for merging and updating the '''Trunk Area''' with code changes in the '''Development 18 Area''' spanning from revision: "''''4869'''" to the "'''HEAD (4877)'''" (latest changes committed to the ''dev/18'' area). Use the following link for NST code revision reference: http://nst.svn.sourceforge.net/viewvc/nst

[root@dev16-32 repo]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
[root@dev16-32 repo]# svn proplist
Properties on '.':
svn:mergeinfo
svn:ignore
[root@dev16-32 repo]# svn propget svn:mergeinfo
/dev:4409-4503,4516-4793
/dev/18:4795-4869
/maintenance/18:4794
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@dev16-32 repo]# svn merge -r 4869:HEAD ${SVNROOT}/dev/18 .
[root@dev16-32 repo]# svn propget svn:mergeinfo
/dev:3590,3592-3611,3613-3614,3616,3618-3620,3622,3624-3627,3629-3702
[root@dev16-32 repo]# svn status -u
... shows files that were updated by the merge ...
[root@dev16-32 repo]# svn commit -m "Merging up to 4877 from dev/18 - new release of the NST WUI"
... output from commit ...
[root@dev16-32 repo]#

== Merging From ''repo'' To ''dev'' Area ==

The easy method for merging the ''repo'' area changes into your ''dev'' area:

* Make sure all code is committed and everything is up to date.
* Set SVNROOT to point to the top level directory (like: https://svn.code.sf.net/p/nst/code).
* Run the merge command as shown below:

[pkb@chimi dev]$ svn merge $SVNROOT/repo/22 .
--- Merging differences between repository URLs into '.':
U include/dist/release-notes.txt
U include/manifest/current.xml
A include/manifest/release-22-7248.xml
U include/data/configure.in
U html/include/make/makefile
U html/links.html
U html/side.html
U html/welcome.html
U html/README.html
U src/scripts/nstmenu/share/groups/release.group.xml
U src/scripts/nstmenu/share/applications/release.apps.xml
U yum/pkgs/nstmenu/template.spec
U yum/pkgs/nstmenu/pkginfo.xml
U yum/pkgs/nstweb/template.spec
U yum/pkgs/nstweb/pkginfo.xml
U .
--- Recording mergeinfo for merge between repository URLs into '.':
U .
[pkb@chimi dev]$

The following demonstrates an older technique that merges the '''Development Area''' with code changes in the '''Repo Area''' spanning from revision: "''''6534''" to "'''HEAD (6537)'''".

'''On repo:'''
[root@vortex repo]# svn propget svn:mergeinfo
/dev:4409-4503,4516-4793
/dev/18:4795-5411,5419-5496
/dev/20:5419-5501,5503-6533
/maintenance/18:4794
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@vortex repo]#

'''On Dev:'''
[root@vortex dev]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
Status against revision: 6533
[root@vortex dev]# svn merge -r 6534:HEAD ${SVNROOT}/repo .
[root@vortex dev]# svn propget svn:mergeinfo
/dev/18:5419-5496
/repo:4494,4505-4514,4516-4551,4555-4568,4586-4587,4614,4695,4717,4781,4812,5413-5415,5662-5666,6535-6537
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@vortex dev]# svn status -u
... shows files that were updated by the merge ...
[root@vortex dev]# svn commit -m "Merging up to 6537 from repo for new release"
... output from commit ...
[root@vortex dev]#

== Switching To A New Root ==

There can be many different branches of the same source tree at different levels of development within the Subversion repository. You can use the ''switch'' command to switch from one branch to another. When making a switch, the source code you have checked out will be updated to match the state of the source code in the new branch. Before making a switch, it is important to make sure that all of your changes are checked into the current branch. For example, the following demonstrates how to switch to the ''dev'' branch from the ''trunk'' branch:

[root@taco-dev32 repo]# svn info
Path: .
Working Copy Root Path: /root/repo
URL: https://svn.code.sf.net/p/nst/code/repo
Relative URL: ^/repo
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 6540
Node Kind: directory
Schedule: normal
Last Changed Author: rwhalb
Last Changed Rev: 6540
Last Changed Date: 2015-02-09 13:57:38 -0500 (Mon, 09 Feb 2015)

[root@taco-dev32 repo]# export SVNROOT="$(svn info | awk -- '$2 == "Root:" { print $3; }')";
[root@taco-dev32 repo]# echo $SVNROOT
https://svn.code.sf.net/p/nst/code
[root@taco-dev32 repo]# svn switch $SVNROOT/dev/20
At revision 3577.
[root@taco-dev32 repo]#

After making a switch, you can use the ''info'' command to verify the switch was successful.

[root@taco-dev32 repo]# svn info
Path: .
URL: https://nst.svn.sourceforge.net/svnroot/nst/dev
Repository Root: https://nst.svn.sourceforge.net/svnroot/nst
Repository UUID: c9574408-7c70-44fe-bb37-9fe24d5f8586
Revision: 3577
Node Kind: directory
Schedule: normal
Last Changed Author: jdoe
Last Changed Rev: 3577
Last Changed Date: 2012-05-29 10:04:54 -0400 (Tue, 29 May 2012)

[root@taco-dev32 repo]#

== Relocate To A New Repository Root ==

This section demonstrates switching repository root from one URL to another. In this example we switch from "'''http://svn.code.sf.net/p/nst/code'''" to "'''svn+ssh://USERID@svn.code.sf.net/p/nst/code'''". The svn "'''relocate'''" command is used.

[root@vortex dev]# svn info;
Path: .
Working Copy Root Path: /root/dev
URL: http://svn.code.sf.net/p/nst/code/dev/26
Relative URL: ^/dev/26
Repository Root: http://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 9274
Node Kind: directory
Schedule: normal
Last Changed Author: user
Last Changed Rev: 9274
Last Changed Date: 2017-10-11 16:07:51 -0400 (Wed, 11 Oct 2017)
[root@vortex dev]#
[root@vortex dev]# svn --username USERID relocate http://svn.code.sf.net/p/nst/code svn+ssh://USERID@svn.code.sf.net/p/nst/code;

= Related Links =

; http://nst.svn.sourceforge.net/viewvc/nst
: Use this link to browse the NST Subversion repository (the 'trunk' folder corresponds to the current development tree).

NST Avahi (mDNS) FAQ

2019-04-22T21:22:01Z

Paul Blankenbaker: Cleaned up how to fix AT&T router issue

NST Avahi (mDNS) FAQ

2019-04-22T21:20:14Z

Paul Blankenbaker: Created page with "__TOC__ = Avahi/mDNS General = == What Services Need to Be Running? == The ''avahi-daemon.service'' needs to be running. You can check its status via: systemctl status av..."

FAQ

2019-04-22T20:57:11Z

Paul Blankenbaker:

* [[Common Recovery and Removal Questions]]
* [[Disk Images]]
* [[Google Applications]]
* [[Graphical Desktop (X) Questions]]
* [[Hard Disk Installation]]
* [[Installing Adobe Flash And Reader]]
* [[Installing VideoLAN VLC Media Player]]
* [[Installing "gstreamer1-libav" for the Parole Media Player]]
* [[Java Questions]]
* [[Live Boot Differences]]
* [[NST and Virtual Machines]]
* [[NST Avahi (mDNS) FAQ]]
* [[NST Bluetooth FAQ]]
* [[NST Boot FAQ]]
* [[NST General Information]]
* [[NST USB FAQ]]
* [[Serial Ports]]
* [[Source Code]]
* [[SQL Questions]]
* [[Trouble Shooting]]
* [[Updating A NST System]]
* [[Wireless]]

Subversion Notes

2018-12-15T14:45:42Z

Paul Blankenbaker: /* Revert */

We switched from using CVS to Subversion as our source control mechanism in mid October 2009.

* We did not try to import all of the CVS history.
* The initial import includes all of the 2.11.0 release source plus the updated source code since the release (the state of CVS on 2009-10-14).
* We left the CVS repository alone (in case we ever wanted to refer back for older history).

= Preparing Development Machine =

As a developer, the following things must be done to your development machine before you will be able to check out, build and commit changes to the NST source code.

== Set SVNROOT ==

You need to set the ''SVNROOT'' variable. Add the following to your '''~/.bashrc''' or '''~/.bash_profile''' configuration file:

export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst

After the ''SVNROOT'' variable is set, you should be able to run Subversion commands. For example the following shows the directories under ''SVNROOT''.

[pkb@sprint ~]$ export SVNROOT=https://nst.svn.sourceforge.net/svnroot/nst
[pkb@sprint ~]$ svn ls ${SVNROOT}
trunk/
[pkb@sprint ~]$

== gnome-keyring ==

Subversion might complain about needing to store passwords in a ''unencrypted'' form. To prevent this, we need to figure out how to enable the ''gnome-keyring'' add-on. To do this, edit the file '''~/.subversion/config''' and search on the string ''password-stores''. Most likely this will be commented out in your current configuration file. I updated mine to the following:

password-stores = gnome-keyring

However, this was not enough to prevent me from being prompted each time. I then added the following package:

yum install subversion-gnome

We will see if this permits us to store the password or not (you may need to be logged into a GNOME desktop in order to make use of the gnome-keyring feature).

= Directory Structure =

Currently the directory structure under Subversion is fairly straight forward. We use ''trunk'' as the current working area (this is what most developers will be checking out from and committing to). When we have a release, we will copy ''trunk'' to the release number. For example, to create the ''2.13.0'' release, we would run the following Subversion command:

svn copy ${SVNROOT}/trunk ${SVNROOT}/releases/2.13.0

We would also run the following command for maintenance updates to the ''2.13.0'' release:

svn copy ${SVNROOT}/trunk ${SVNROOT}/maintenance/2.13.0

= Subversion Commands =

Use the following to get the list of available subversion commands:

svn help

To get more information about a specific Subversion command (like ''ls''), run:

svn help ls

== Checking Out Code ==

To make the initial checkout of the current source code into a sub-directory named ''nst'', you can use the following Subversion command:

svn co ${SVNROOT}/trunk nst

== Committing Code ==

You use the ''commit'' subversion command when you want to commit changes to the source code.

When you first run ''commit'', it may prompt you for the password for the incorrect user ID. If this happens, press the ''Enter'' key without specifying a password. This should allow you enter your SourceForge user ID followed by your SourceForge password when committing changes. For example:

[root@fedora11 nightly]# svn commit
Authentication realm: <https://nst.svn.sourceforge.net:443> SourceForge Subversion area
Password for 'root':
Authentication realm: <https://nst.svn.sourceforge.net:443> SourceForge Subversion area
Username: SOURCEFORGE_LOGIN_ID
Password for 'SOURCEFORGE_LOGIN_ID':
Sending nightly/nightly-build.bash
Sending nightly/nightly2html.xsl
Sending nightly/nightly2txt.xsl
Transmitting file data ...-----------------------------------------------------------------------
ATTENTION! Your password for authentication realm:

<https://nst.svn.sourceforge.net:443> SourceForge Subversion area

can only be stored to disk unencrypted! You are advised to configure
your system so that Subversion can store passwords encrypted, if
possible. See the documentation for details.

You can avoid future appearances of this warning by setting the value
of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
'/root/.subversion/servers'.
-----------------------------------------------------------------------
Store password unencrypted (yes/no)? no

Committed revision 4.
[root@fedora11 nightly]#

== Status ==

The Subversion status command is very handy at showing not only what files you've modified, but also (when including the ''-u'' option) handy at showing what files have changed in the repository:

svn status -u

For help about the output of ''svn status'', run:

svn help status | less

== Revert ==

If you've made modifications to a file which you want to discard, use the ''revert'' command to restore the original version:

svn revert FILENAME

To revert back to a previous revision use the '''merge''' option. The follow example reverts back to the '''3986''' revision from the '''3987''' revision for file: "'''bwmonitor.js'''". After the revert changes are applied you will need to '''commit'''. Use the [http://nst.svn.sourceforge.net/viewvc/nst/ Subversion Browser] to assit in finding your revision numbers.

svn merge -r 3987:3986 bwmonitor.js

== Revert Commit, Undo Commit, Reverse Merge ==

If you've committed modifications to a file accidentally it is a bit tricky to ''undo'' the commit. To get back an older version you need to perform something called a reverse merge. This is done by running the ''svn merge -r BAD:GOOD SOURCE'' command. Where BAD is typically the current revision ID of the source you want to revert, GOOD is the revision ID of the good code you want to restore and is typically 1 less than the value of BAD. SOURCE is typically the name of the file or directory you want to undo the commit on.

For example, we can used the following command to determine the last changed revision of the files under the current directory:

[pkb@refritos server]$ svn info . | grep Rev:
Last Changed Rev: 10660
[pkb@refritos server]$

In this example the BAD revision ID is 10660 associated with the last commit done to this area. To restore the files to the 10659 state (the good version prior to the 10660) state, we would run the following command:

[pkb@refritos server]$ svn merge -r 10660:10659 .
--- Reverse-merging r10660 into '.':
U xrdp.cgi
--- Recording mergeinfo for reverse merge of r10660 into '.':
G .
--- Eliding mergeinfo from '.':
U .
[pkb@refritos server]$

As the ''status'' command shows, this undo only impacted one file in the directory and is not immediately reflected in the repository.

[pkb@refritos server]$ svn status
M xrdp.cgi
[pkb@refritos server]$

This allows us to inspect the undone changes. If we are happy, we can commit this version back. If we are unhappy with the results, we can revert the state of the directory and try again.

== Ignoring Files ==

Under CVS, you could edit the file '''.cvsignore''' to tell CVS to ignore certain files within the directory. Subversion has a similar, but different mechanism for ignoring files. Basically, you change to the directory where the files/directories to be ignored exist and run the following command:

svn propedit svn:ignore .

Running the above command should pull up a text editor and allow you to specify file name patterns to specify what files and directories should be ignored. Here is an example ignore list which causes Subversion to ignore any file or directory ending with the extension ''.log'' or having the name ''tmp'':

*.log
tmp

== Manage The Executable Flag On File ==
Use the following command to set the executable flag on a file (e.g., bwmonitor-ajax.php)under SVN control:

svn propset svn:executable bwmonitor-ajax.php

Use the following command to remove the executable flag on a file (e.g., bwmonitor-ajax.php)under SVN control:

svn propdel svn:executable bwmonitor-ajax.php

== Merging Changes Across Revisions ==

Our general strategy is typically to do all new work under the ''trunk'' area. However, when we move from one Fedora platform to another (like from Fedora 13 to Fedora 15), we will typically copy the ''trunk'' area to a sub-directory under the maintenance area. For example, the following shows the top level Subversion heirarchy (where you will see ''trunk'' and ''maintenance'') and the number of older maintenance areas where we have the ability to maintain older versions of the software.

[root@f13-32 ~]# svn ls $SVNROOT
maintenance/
releases/
trunk/
[root@f13-32 ~]# svn ls $SVNROOT/maintenance
2.11.0/
2.12.0/
2.13.0/
[root@f13-32 ~]#

In this situation, you may find yourself making changes to the ''trunk'' area that you would also like to apply to the ''2.13.0'' branch area. To accomplish this, use the following strategy:

* Make your updates to the ''trunk'' area.
* Commit your changes.
* Determine the range of revision numbers for your change using the [http://nst.svn.sourceforge.net/viewvc/nst/ Subversion browser].
* Use the ''svn merge'' command to merge the changes into the ''maintenance/2.13.0'' area.

Here is an example of using ''svn merge'' to merge the changes made for the 2.1.6 release of the relaycheck package from the ''trunk'' area to the ''maintenance/2.13.0'' area:

* From looking at the [http://nst.svn.sourceforge.net/viewvc/nst/maintenance/2.13.0/yum/pkgs maintenance/2.13.0/yum/pkgs/relaycheck revision number], I can see that the last revision number for the ''maintenance/2.13.0'' version was 2016 (at the time of this writing - it will change in the future).
* From looking at the [http://nst.svn.sourceforge.net/viewvc/nst/trunk/yum/pkgs trunk/yum/pkgs/relaycheck revision number], I can see that the current revision number for the ''trunk'' version of relaycheck was 2102 (at the time this article was written).
* At this point I have enough information to merge the changes with the following ''svn merge'' command:

[root@f13-32 repo]# svn info
Path: .
URL: https://nst.svn.sourceforge.net/svnroot/nst/maintenance/2.13.0
Repository Root: https://nst.svn.sourceforge.net/svnroot/nst
Repository UUID: c9574408-7c70-44fe-bb37-9fe24d5f8586
Revision: 2076
Node Kind: directory
Schedule: normal
Last Changed Author: pblankenbaker
Last Changed Rev: 2076
Last Changed Date: 2011-05-10 16:53:57 -0400 (Tue, 10 May 2011)

[root@f13-32 repo]# svn merge -r 2016:2102 $SVNROOT/trunk/yum/pkgs/relaycheck yum/pkgs/relaycheck
--- Merging r2076 through r2102 into 'yum/pkgs/relaycheck':
U yum/pkgs/relaycheck/src/relaycheck.pl
U yum/pkgs/relaycheck/pkginfo.xml
U yum/pkgs/relaycheck/relaycheck.template.spec
[root@f13-32 repo]# svn status
M yum/pkgs/relaycheck
M yum/pkgs/relaycheck/src/relaycheck.pl
M yum/pkgs/relaycheck/pkginfo.xml
M yum/pkgs/relaycheck/relaycheck.template.spec
[root@f13-32 repo]#

At this point, we should make sure the merged changes still build and then commit our changes.

NOTE: After committing the changes, the [http://nst.svn.sourceforge.net/viewvc/nst/maintenance/2.13.0/yum/pkgs maintenance/2.13.0/yum/pkgs/relaycheck revision number] changed to 2103 (at the time of this writing) which is now larger than the original 2102 revision we used for the merge.
[root@f13-32 repo]# cd yum
[root@f13-32 yum]# make relaycheck

... Omitted much of the output ...

-------------------------------------------------------------------------------
SUCCESS: Successfully installed relaycheck-1.2.6-11.nst13.noarch.rpm
-------------------------------------------------------------------------------
make[1]: Leaving directory `/root/repo/yum/pkgs/relaycheck'
[root@f13-32 yum]# svn commit

== Merging From Dev Area To The Repo Area ==

* '''Note:''' If this merge includes updates in the '''nstwui''' package: '''Have You Updated The NST WUI Release Number On The Dev Branch First?'''

The following demonstrates the current merge method to bring changes from the ''dev/20'' development branch to the ''repo/20'' area.

[root@dev20-64 ~]# cd repo
[root@dev20-64 repo]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
[root@dev20-64 repo]# svn info
Path: .
Working Copy Root Path: /root/repo
URL: https://svn.code.sf.net/p/nst/code/repo/20
Relative URL: ^/repo/20
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 6545
Node Kind: directory
Schedule: normal
Last Changed Author: rwhalb
Last Changed Rev: 6545
Last Changed Date: 2015-02-14 08:44:42 -0500 (Sat, 14 Feb 2015)

[root@dev20-64 repo]# svn update; svn merge https://svn.code.sf.net/p/nst/code/dev/20 .
At revision 6594.
--- Merging r6545 through r6594 into '.':
U include/javascript/core/NstSelect.js
U include/javascript/core/NstRuler.js

...

U yum/pkgs/putty-win32
--- Recording mergeinfo for merge of r6545 through r6594 into '.':
U .
--- Recording mergeinfo for merge of r6545 through r6594 into 'yum/pkgs/putty-win32':
G yum/pkgs/putty-win32
[root@dev20-64 repo]# svn commit -m "Merging up to 6545 from dev/20"
... output from commit ...
[root@dev20-64 repo]#

This is the old method used for merging and updating the '''Trunk Area''' with code changes in the '''Development 18 Area''' spanning from revision: "''''4869'''" to the "'''HEAD (4877)'''" (latest changes committed to the ''dev/18'' area). Use the following link for NST code revision reference: http://nst.svn.sourceforge.net/viewvc/nst

[root@dev16-32 repo]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
[root@dev16-32 repo]# svn proplist
Properties on '.':
svn:mergeinfo
svn:ignore
[root@dev16-32 repo]# svn propget svn:mergeinfo
/dev:4409-4503,4516-4793
/dev/18:4795-4869
/maintenance/18:4794
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@dev16-32 repo]# svn merge -r 4869:HEAD ${SVNROOT}/dev/18 .
[root@dev16-32 repo]# svn propget svn:mergeinfo
/dev:3590,3592-3611,3613-3614,3616,3618-3620,3622,3624-3627,3629-3702
[root@dev16-32 repo]# svn status -u
... shows files that were updated by the merge ...
[root@dev16-32 repo]# svn commit -m "Merging up to 4877 from dev/18 - new release of the NST WUI"
... output from commit ...
[root@dev16-32 repo]#

== Merging From ''repo'' To ''dev'' Area ==

The easy method for merging the ''repo'' area changes into your ''dev'' area:

* Make sure all code is committed and everything is up to date.
* Set SVNROOT to point to the top level directory (like: https://svn.code.sf.net/p/nst/code).
* Run the merge command as shown below:

[pkb@chimi dev]$ svn merge $SVNROOT/repo/22 .
--- Merging differences between repository URLs into '.':
U include/dist/release-notes.txt
U include/manifest/current.xml
A include/manifest/release-22-7248.xml
U include/data/configure.in
U html/include/make/makefile
U html/links.html
U html/side.html
U html/welcome.html
U html/README.html
U src/scripts/nstmenu/share/groups/release.group.xml
U src/scripts/nstmenu/share/applications/release.apps.xml
U yum/pkgs/nstmenu/template.spec
U yum/pkgs/nstmenu/pkginfo.xml
U yum/pkgs/nstweb/template.spec
U yum/pkgs/nstweb/pkginfo.xml
U .
--- Recording mergeinfo for merge between repository URLs into '.':
U .
[pkb@chimi dev]$

The following demonstrates an older technique that merges the '''Development Area''' with code changes in the '''Repo Area''' spanning from revision: "''''6534''" to "'''HEAD (6537)'''".

'''On repo:'''
[root@vortex repo]# svn propget svn:mergeinfo
/dev:4409-4503,4516-4793
/dev/18:4795-5411,5419-5496
/dev/20:5419-5501,5503-6533
/maintenance/18:4794
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@vortex repo]#

'''On Dev:'''
[root@vortex dev]# svn status -u # MAKE SURE YOU ARE COMMITTED AND UP TO DATE FIRST!
Status against revision: 6533
[root@vortex dev]# svn merge -r 6534:HEAD ${SVNROOT}/repo .
[root@vortex dev]# svn propget svn:mergeinfo
/dev/18:5419-5496
/repo:4494,4505-4514,4516-4551,4555-4568,4586-4587,4614,4695,4717,4781,4812,5413-5415,5662-5666,6535-6537
/trunk:3591,3657-3699,3951,4042,4102-4106,4112,4145-4155,4196,4232-4240
[root@vortex dev]# svn status -u
... shows files that were updated by the merge ...
[root@vortex dev]# svn commit -m "Merging up to 6537 from repo for new release"
... output from commit ...
[root@vortex dev]#

== Switching To A New Root ==

There can be many different branches of the same source tree at different levels of development within the Subversion repository. You can use the ''switch'' command to switch from one branch to another. When making a switch, the source code you have checked out will be updated to match the state of the source code in the new branch. Before making a switch, it is important to make sure that all of your changes are checked into the current branch. For example, the following demonstrates how to switch to the ''dev'' branch from the ''trunk'' branch:

[root@taco-dev32 repo]# svn info
Path: .
Working Copy Root Path: /root/repo
URL: https://svn.code.sf.net/p/nst/code/repo
Relative URL: ^/repo
Repository Root: https://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 6540
Node Kind: directory
Schedule: normal
Last Changed Author: rwhalb
Last Changed Rev: 6540
Last Changed Date: 2015-02-09 13:57:38 -0500 (Mon, 09 Feb 2015)

[root@taco-dev32 repo]# export SVNROOT="$(svn info | awk -- '$2 == "Root:" { print $3; }')";
[root@taco-dev32 repo]# echo $SVNROOT
https://svn.code.sf.net/p/nst/code
[root@taco-dev32 repo]# svn switch $SVNROOT/dev/20
At revision 3577.
[root@taco-dev32 repo]#

After making a switch, you can use the ''info'' command to verify the switch was successful.

[root@taco-dev32 repo]# svn info
Path: .
URL: https://nst.svn.sourceforge.net/svnroot/nst/dev
Repository Root: https://nst.svn.sourceforge.net/svnroot/nst
Repository UUID: c9574408-7c70-44fe-bb37-9fe24d5f8586
Revision: 3577
Node Kind: directory
Schedule: normal
Last Changed Author: jdoe
Last Changed Rev: 3577
Last Changed Date: 2012-05-29 10:04:54 -0400 (Tue, 29 May 2012)

[root@taco-dev32 repo]#

== Switching To A New URL ==
This section demonstrates switching from one URL to another. In this example we switch from "'''http://svn.code.sf.net/p/nst/code/dev/26'''" to "'''svn+ssh://USERID@svn.code.sf.net/p/nst/code'''". The svn "'''switch'''" command with option: "'''--relocate'''" is used.

[root@vortex dev]# svn info;
Path: .
Working Copy Root Path: /root/dev
URL: http://svn.code.sf.net/p/nst/code/dev/26
Relative URL: ^/dev/26
Repository Root: http://svn.code.sf.net/p/nst/code
Repository UUID: b5e161f0-cc72-4f2a-9017-da5bd5071a9c
Revision: 9274
Node Kind: directory
Schedule: normal
Last Changed Author: user
Last Changed Rev: 9274
Last Changed Date: 2017-10-11 16:07:51 -0400 (Wed, 11 Oct 2017)
[root@vortex dev]#
[root@vortex dev]# svn --username USERID switch --relocate http://svn.code.sf.net/p/nst/code/dev/26 svn+ssh://USERID@svn.code.sf.net/p/nst/code/dev/26;

= Related Links =

; http://nst.svn.sourceforge.net/viewvc/nst
: Use this link to browse the NST Subversion repository (the 'trunk' folder corresponds to the current development tree).