Install and update

Install

On Linux and macOS, install the np command with:

curl -sS https://get.nanoping.com | sh

It puts np in ~/.local/bin, a directory you own, so the node can update itself, and links /usr/local/bin/np to it, so that sudo np finds it. Where only root can create the link, it uses sudo, which asks for your password. It asks you two things:

• Whether to remove an older np. If an older installer put np somewhere else, such as /usr/local/bin, the installer asks before it starts whether to remove that one once the new one is installed. Where only root can remove it, it uses sudo, which asks for your password.
• Whether to add ~/.local/bin to your PATH. Unless it is there already, the installer offers to add it in your shell's startup files, such as ~/.bashrc, ~/.zshrc and ~/.profile. New terminals pick it up. The line ends in # added by the NanoPing installer.

Run the installer again to install the newest release over the one you have.

Then start NanoPing with:

sudo np up

sudo does not look for commands in your home directory, so without the link, give it the path to np, as in sudo ~/.local/bin/np up. The installer says when it could not make the link, and which command to run.

If you keep an older np in /usr/local/bin, the installer leaves it there instead of the link, and sudo np runs that older one.

Installer options

These variables change what the installer does. Without a terminal to ask on, it answers no to both questions.

Variable	Effect
NANOPING_INSTALL_DIR=<dir>	Install np in another directory, without the link in /usr/local/bin.
NANOPING_LINK_DIR=<dir>	Make the link in another directory than /usr/local/bin.
NANOPING_MODIFY_PATH=yes or no	Answer the PATH question without asking.
NANOPING_REMOVE_OLD=yes or no	Answer the question about an older np without asking.

Set them on sh, as in curl -sS https://get.nanoping.com | NANOPING_MODIFY_PATH=yes sh.

App data

The node keeps its data, such as its settings, pipelines and license, in nanoping in your home directory, also when started with sudo. In a root shell it is in root's home directory instead. To keep it elsewhere, give --app-data <dir> before the command, on every command, as in sudo np --app-data /srv/nanoping up.

Run as a service

To start the node at boot and bring it back if it fails, install it as a service:

sudo np service install

It takes the options of np up, which the service then starts with every time, and the global ones such as -c:

sudo np -c ~/nanoping.yaml service install --http 0.0.0.0:8081

On Linux it writes a systemd unit, /etc/systemd/system/nanoping.service, and on macOS a launchd job, /Library/LaunchDaemons/com.nanoping.np.plist. It then starts the node, and waits until it runs. Run it again to change the options. To stop the service and remove it:

sudo np service uninstall

How the service runs:

• As root, on your app data. The service keeps the node's data where sudo np up does, so sudo np down and the other commands find it.
• Stopping sends SIGTERM to np alone. np stops its pipelines itself, the same way np down does. A pipeline that does not stop when asked is sent SIGTERM, then SIGKILL.
• The system has the final say. Whatever is still running a minute after the stop began is killed, np and its pipelines alike, so a node too loaded to stop cleanly still stops.
• Updates keep the service. A node that updates itself restarts in the same process, so the system keeps following it.

On Linux, systemctl status nanoping shows how the service is doing, and journalctl -u nanoping its output.

Run without sudo

On Linux, np can run as your own user once it holds the capabilities it needs to create network interfaces:

sudo setcap 'cap_net_admin,cap_net_raw,cap_dac_override=ep' ~/.local/bin/np

cap_dac_override lets pipelines use performance mode on a pinned CPU thread; leave it out if you do not need that. Give the path to the file itself, not the link in /usr/local/bin. Without the capabilities, np up says which ones are missing and how to grant them.

A new np file does not have them, so run setcap again after you run the installer, and update such a node with sudo np update while it is stopped (see What a node needs to update itself). On macOS, np still needs sudo.

Update

A node updates itself to the newest release on its channel. It looks for one every six hours, and when you ask it to. Installing a release restarts the node, which interrupts its running pipelines.

Channels

Every node gets stable releases. An organization can also be given beta and experimental builds, such as 11.1.0-beta1_<commit>, and a node can follow one of those channels as well. It is then offered the newest of that channel's builds and the stable releases. A node follows the channel of the build it was first started on until you pick another.

The Releases page, opened from the version in the dashboard's footer, lists every release your organization can get with its release notes, on stable and on its channels.

You can also install any version your organization can get, older ones included. Picking a version moves the node to that version's channel. When a newer release on that channel would replace the version you picked, automatic installs are turned off, so they do not undo your pick. Restoring a backup does the same.

Backups

Every install keeps the version it replaces as a backup, with a copy of the node's app data unless Back Up App Data is off. Logs and pipeline runs are left out. Backups are kept until you delete them, and restoring one keeps the version it replaces as a new backup.

Installing a version the node has a backup of restores that backup, app data and all, instead of downloading it.

An older version cannot read the app data a newer one left, so installing an older version without a backup starts it on clean app data: without its pipelines and settings, off the hub, and waiting to be claimed again. The current app data is backed up first, whatever Back Up App Data says, so once the node is claimed again, restoring that backup brings everything back.

Free space

An install or restore leaves at least Keep Free Space free on the disk, 1000 MB unless you set it. Before it downloads anything or restarts the node, it adds up everything it will write: the backup of the running version with its app data, the new executable and, for an install, the download. When that would leave less than the space to keep free, it is refused and the node keeps running; the error says how much it needs and how much is free. Delete backups to make room, or lower the space to keep free. Set it to 0 to leave the space unchecked.

Automatic installs are held to it too. The rollback after a new version does not start is not, so it always goes ahead.

From the dashboard

Open the node's Settings from the Nodes section and pick Updates from the menu. The page shows the version the node runs and the newer release it found, if any:

• Check now looks for a newer release, and for the versions the node can get.
• Update to downloads the newer release and restarts the node on it. If the new version does not start, the node goes back to the version it ran before, and points to the log that says why.
• Channel picks the channel the node follows besides stable.
• Install Updates Automatically has the node install a newer release on its channel as soon as it finds one.
• Back Up App Data keeps a copy of the node's data with each version an install replaces.
• Keep Free Space is the space, in MB, an install or restore has to leave free on the disk.
• Versions lists every version the node can get, newest first. Install on one says what installing it means before it goes ahead.
• Backups lists the backups and the space they take. Each can be restored or deleted, and Delete all deletes every one.

Every node on the hub can be updated this way, from any node's dashboard.

From the command line

Command	What it does
np update	Installs the newest release on the node's channel and restarts onto it
np update --check	Only looks for a newer release
np update --version <version>	Installs that version, older ones included, and moves the node to its channel. An older version without a backup needs --yes
np update list	Lists the versions the node can get
np update status	Shows the version, the newest release, the backups and the update settings
np update rollback	Restores the newest backup
np update backups	Lists the backups and the space they take
np update backups restore <id or version>	Restores a backup
np update backups delete <id or version>	Deletes a backup, or every backup with --all
np update settings --channel beta --auto-install --backup-app-data=false --keep-free 2000	Changes the update settings. --channel stable follows stable alone, and --keep-free 0 leaves the space unchecked

Each of them takes --node <id or name> to act on another node on the hub.

They also work while the node is stopped, such as when a new version does not start. Installing and restoring then replace the executable in place, and the node starts on it with np up.

What a node needs to update itself

• A license. The node fetches releases with the license it was activated with.

• Write access to its executable. The new release replaces the np file the node runs, so the user the node runs as has to be able to write to the directory it is in. The installer puts np in ~/.local/bin, which you own, so a node updates itself whether you start it with sudo or as yourself. An np in a directory only root can write to, such as /usr/local/bin from an older installer, updates only when the node runs as root. Run the installer again to move it.

• Root, for capabilities set with setcap. A new version is a new file, and only root can give it the capabilities the old one had. A node that runs as a regular user on such capabilities updates with sudo np update while it is stopped. Granting the capabilities through systemd's AmbientCapabilities instead avoids that.

When a node cannot update itself, Settings and np update status say why.

In the config file

The update settings can be set in the config file as well:

updates:
  channel: beta
  autoInstall: true
  backupAppData: false
  keepFreeMb: 2000