Skip to main content

Hydra Snap Packages Usage Guide

Installation and Initialization​

This a quick installation guide to have the Snap ready to run with default configurations and settings. You would likely want to adapt the setup depending on your situation. Therefore, we invite you to have a look at the other section too in order to set up the Snap according to your needs.

note

Throughout this document, we use {snap-name} as a placeholder for the name of the Snap package. To get the complete list of the Snap packages, contact us to check your subscription plan.

danger

If your user is logged into Snap Store, you might be able to install the Snap package without the need to use sudo, however this method is not suggested. You should always use sudo to install the Snap packages.

tip

If you have faced any issues following the documentation, perhaps you may need a fresh installation of the Snap package. In that case simply use the following command to purge the older installations of the Snap.

sudo snap remove {snap-name} --purge

This command will have no effect if there are no older version of the snap installed.

Installing the Snap packages​

For installing the Snap packages, you have four options:

  1. Install from the Snap Store
  2. Install from Harbor (SUGGESTED)
  3. Install from the local .snap files
  4. Install the source code (available only for DevOps access)
danger

Certain Snap packages currently could work ONLY with the --devmode flag. This is mainly to support arbitrary hardware requirements or extra permissions that they need. The list of those Snap packages are:

  • amr-cn: required for the extra permissions for IMS service, otherwise it is fine to install without --devmode
  • amr-ran: required for the access to Amarisoft SDR cards
  • oai-ue: required for the access to Quectel UE modules

We are continuously working on removing the --devmode flag from the Snap packages by collaboration with Canonical to add the support for the required features. The flag should be appended to every installation command, regardless of the installation method.

Installing from the Snap Store​

Most of the packages are available in the Snap Store, but perhaps they are only accessible to private users. If you have Snap Store login access, you could directly run:

sudo snap install {snap-name}
caution

Given a private Snap, if you are not logged in, or you do not have the proper access rights, this method will fail. You could try to log in using the command:

sudo snap login

Then you fill in your email address and the password. The email address should be associated with an Ubuntu One account.

Snap packages are distributed on channels. Each channel is composed of a version (or a track) and risk level separated by a slash. The risk level is one of stable, candidate, beta, or edge and the version could be latest among others. The default channel for installation is always latest/stable. You could specify a different channel using the --channel flag. Also, --stable, --candidate, --beta, and --edge flags are available for tracking a specific risk level of the latest version. For more information about the channels, please refer to the Snap documentation.

Each installation of a Snap package, regardless of the method is done in a revision. The revision is a unique identifier for the installation. You could view the parameters of an installed Snap package using the following command:

snap list {snap-name}

And to fetch the information from the Snap Store, you could use the following command: (login required for private Snap packages)

snap info {snap-name}

Installing from Harbor​

We independently host the Snap packages in our private Harbor registry. To download and install the Snap packages you need to have ORAS installed on your machine. The DevOps machines provided by BubbleRAN have already ORAS installed.

Then you need to log in to our Harbor registry, which again is done automatically on the DevOps machines. If you have Docker installed, and it is already logged into your account on Harbor, you could skip the login. Otherwise, you need to log in using the following command, and use your credentials:

oras login hub.bubbleran.com

After logging in you need to pull the artifact from the registry:

oras pull hub.bubbleran.com/{vendor-name}/{snap-name}:snap

Finally, you could install the Snap package using the following commands:

sudo snap ack {snap-name}.assert
sudo snap install {snap-name}.snap

Installing from the local .snap files​

If you have the .snap file locally, you could install it using the following command:

sudo snap install --dangerous {file-path}
note

The dangerous flag is required because the Snap package is not signed by the Snap Store.

tip

Snapd keeps a cache of the Snap packages that you have installed. You could find them under /var/lib/snapd/snaps with the filename convention of {snap-name}_{revision}.snap. You may copy these files to another machine and install them using the --dangerous flag.

caution

Installing the Snap packages using this method would result in revision numbers starting with x instead of actual values that are used in the Snap Store.

Installing from source​

After cloning the Hydra repository, you could build and install the Snap package from the source code. Source code access is only available for DevOps customers.

make ACTIVE_ELEMENTS={vendor-name}/{snap-name} install-snap

This receipt already connects the plugs so that you can skip the Plugs section and go directly to the Initialize section.

Plugs​

The Snap packages require certain permissions to access the hardware and the system. These permissions are expressed via Snap interfaces. Each interface sets a set of rules that the Snap package needs to follow in order to access the hardware. The Snap packages requests an interface by defining a plug and the system (or other Snap packages) implement the interface by defining a slot. The plug needs to be connected to the corresponding slot to grant that interface. For more information about the interfaces, please refer to the Snap documentation.

In order to connect a plug to the default corresponding system slot, you can use the command:

sudo snap connect {snap-name}:{plug-name}

The auto-completion of the {plug-name} is available for this command.

By running the following command you could get the status of all the plugs of a Snap package:

snap connections {snap-name}

The connections that have the Slot field empty are the plugs that are not connected to any slot. Snapd automatically connects some plugs upon installation, but some of them need to be connected manually. When the user connects the plugs manually, under the Notes column you find the message saying manual.

Initialize​

Once all the required plugs are connected, you can proceed with the initialization of the Snap:

sudo {snap-name}.init main

Each Snap package provides certain apps which are mapped to the subcommands of the form {snap-name}.{app-name}. init is the app that initializes Hydra Snap packages. As an optional parameter, you can give the particular {app-name} that you want to initialize, where main is a placeholder for generic initialization. Each particular app could be initialized by running:

sudo {snap-name}.init {app-name}

To get the list of all the apps of a Snap package, you can run:

{snap-name}.help

Running the following command also emits generic information about the Snap package:

{snap-name}.info
{snap-name}.dump-vars
tip

Initialization of the Snap packages needs to be done once per installation or after changing the configuration.

note

The initialization process is idempotent, so it is safe to run it multiple times.

Settings and configuration​

Once you initialized the Snap package, you may want to edit the settings and configurations of the applications.

Settings​

Snapd provides a mechanism to store the settings of the applications. We use this mechanism to store the filenames of the configurations as well as some extra parameters such as NUMA settings. Snaps settings can be displayed in JSON format using

snap get {snap-name} -d

The JSON file should at least have two fields: conf and numa.

Configuration files (conf)​

Under the conf section of the settings are the paths to the configuration files of the applications inside the Snap package. Those paths can be accessed using:

snap get {snap-name} conf.{app-name}

where the path field in the results shows the filepath of the configuration file and the optional type field shows the expected filetype. Alternatively and preferably, you can use the following command to get the path of the configuration file:

{snap-name}.conf-get-{app-name}

or show the content of the configuration file:

{snap-name}.conf-show-{app-name}

You could manually set the path of the configuration file using:

sudo snap set {snap-name} conf.{app-name}.path {new-config-path}

Alternatively and preferably, you could use the following command to set the path of the configuration file:

sudo {snap-name}.conf-set-{app-name} {new-config-path}

In the latter option the filepath given could be relative to the default configuration directory of the Snap package, located at /var/snap/{snap-name}/common/. The command

{snap-name}.conf-list

would list all the files in the said directory in a nice format.

You have the facilities to directly edit the configuration file using:

sudo {snap-name}.conf-edit-{app-name}

where it spawns a VIM editor with the configuration file opened.

caution

If you are not familiar with VIM, you could exit the editor by pressing ESC and then :q! without saving any changes. Then use the composed command below to edit the configuration file with your favorite editor, e.g. nano:

sudo nano $(sudo {snap-name}.conf-get-{app-name})

There is a generator for the configuration files of the applications that depending on the vendor could help you generate the right configuration file by simply asking you a few questions. To use the generator, you can run:

sudo {snap-name}.conf-gen-{app-name}

CPU pining (numa)​

The Hydra Snap packages have the ability to be pinned on given set of cores of the CPU, otherwise known as NUMA. This features allow to limit scheduling overhead or to reduce the side effects of the applications on each other. To know which cores are available on your machine, look at the cpus section in the output of $ numactl --hardware. The pining of the process is determined by the numa settings cpulist and enable.

numa.enable​

The setting numa.enable can have two values: yes or no. CPU pining is enabled only if numa.enable is equal to yes. numa.enable can be set using

sudo snap set {snap-name} numa.enable={yes/no}

numa.cpulist​

A valid list of CPUs is a comma separated list of ranges of CPUs where ranges or CPUs are either the index of one CPU or the indices of two CPUs separated by a dash meaning all the CPUs from the first index to the second. All the indices matched by the list should be in the range of available CPUs. The list can be empty, this will disable the CPU pining even if numa.enable is set to yes.

examples:

  • '' is a valid list since the empty list is valid and will disable CPU pining.
  • '2,3,10,11' is a valid list that matches CPUs 2, 3, 10 and 11.
  • '4-11' is a valid list that matches CPUs 4, 5, 6, 7, 8, 9, 10 and 11.
  • '0,1,4-11' is a valid list that matyches CPUs 0, 1, 4, 5, 6, 7, 8, 9, 10 and 11.
  • '0-1-4-11' is not a valid list.

numa.cpulist can be set using:

sudo snap set {snap-name} numa.cpulist={list}

Using the applications and background services​

You can simply run the applications as a foreground process with the command

sudo {snap-name}.{app-name}

If you simply execute sudo {snap-name} it will run the main app which might correspond to multiple other applications simultaneously.

You can also start some applications as a service with the command

sudo {snap-name}.start-{app-name}

and likewise stop them with

sudo {snap-name}.stop-{app-name}

or restart them with

sudo {snap-name}.restart-{app-name}

Alternatively, you could use the commands

sudo snap {start/stop/restart} {snap-name}.{app-name}d

Please note at the trailing d in the command above.

To get the logs of the background services, you can use the command

sudo {snap-name}.journal-{app-name} --pager-end

or alternatively

sudo snap logs {snap-name}.{app-name}d --pager-end
tip

The --pager-end option will automatically scroll to the end of the logs. You might also append --follow to the command above to follow the logs in real time.

Finally, you could perform start, stop, and restart operations against all the background services of the Snap package by running the corresponding commands:

sudo {snap-name}.start-all
sudo {snap-name}.stop-all
sudo {snap-name}.restart-all

Commands​

Each Snap package offers a variety of commands that you can call by using [sudo] {snap-name}.{command}. Among those commands, there is the help command that actually displays all the commands available and a description of them.

{snap-name}.help

The output generally looks like this:

	--------------------------------------------------------------------------------------------------------
                                            _   _           _
                                            | | | |_   _  __| |_ __ __ _
                                            | |_| | | | |/ _` | '__/ _` |
                                            |  _  | |_| | (_| | | | (_| |
                                            |_| |_|\__, |\__,_|_|  \__,_|
                                                   |___/
	--------------------------------------------------------------------------------------------------------

	{snap-name}, version {version} on snap


	Usage:           {snap-name}.[options] args
	Note:            The options marked with * require root privileges in the environment to work properly.

	Apps             Description
	----------------|---------------------------------------------------------------------------------------
	{app-name}       {app-description}
	...              ...

	Options          Description
	----------------|---------------------------------------------------------------------------------------
	help             print this help
	info             print the package information

	*[app]           run the oai-amf.app as a foreground process
	*start[-app]     start and enable the oai-amf.app as a service daemon, or all if not specified
	*stop[-app]      stop and disable the oai-amf.app daemon service, or all if not specified
	*restart[-app]   restart and re-enable the oai-amf.app daemon service, or all if not specified
	status[-app]     get the oai-amf.app service status, or all if not specified
	journal-[app]    get the oai-amf.app service logs from the system journal, for the specified app

	*init [app]      initialize [app]
	*init install    initialize and restore the settings
	*init restore    initialize, restore the settings, and rollback all the configurations
	dump-vars        dumps all the variables

	conf-list        list all the oai-amf configuration files in their default paths
	*conf-set-[app]  set the oai-amf.app configuration file
	conf-get-[app]   get the address of current oai-amf.app configuration file
	conf-show-[app]  show the contents of the oai-amf.app configuration file
	*conf-gen-[app]  a helper tool to generate the configuration files from templates
	*conf-edit-[app] open up vim to edit the configuration file directly

	...              ...
tip

As denoted by the help command, the commands marked with a * require root privileges.

tip

{snap-name} command is a shortcut for {snap-name}.main.

Generic commands​

help​

Displays the list of available commands with a short description for each.

info​

Displays information about the Snap package. It mainly displays the current configuration of the Snap applications, dumps all the variables and displays the plugs that need to be connected.

init install​

danger

This commands should be run as superuser.

Initializes the Snap as if it has been just installed, including all the applications, and restores its settings. It also prints the snap information like the info command.

init restore​

danger

This commands should be run as superuser.

Initializes the Snap, including all the applications, restores its settings and rolls-back all the configurations to their default values.

dump-vars​

Prints the variables of the snap.

conf-list​

Lists the available configuration files of the applications with their paths.

init {app-name}​

danger

This commands should be run as superuser.

Initializes the {app-name} application.

start-{app-name}​

danger

This commands should be run as superuser.

Starts the application as a background service. Does nothing if the application is already running. When it is running, the application could be restarted by using the restart-{app-name} command or stopped by using the stop-{app-name} command. Also displays the status of all the applications of the snap.

stop-{app-name}​

danger

This commands should be run as superuser.

Stops the application when it is running as a background service. Does nothing if the application is not running. The application could be restarted by using either the start-{app-name} command or the restart-{app-name} command. Also displays the status of all the applications of the snap.

restart-{app-name}​

danger

This commands should be run as superuser.

Restarts the application as a background service. When it is running, the application could be stopped by using the stop-{app-name} command. Also displays the status of all the applications of the snap.

status-{app-name}​

Displays the status of the Snap package services.

journal-{app-name}​

Displays the system journal for that service.

Configuration commands​

conf-set-{app-name}​

danger

This commands should be run as superuser.

Sets the configuration file used to run the {app-name} application. It takes the path of the configuration file you want to use as an argument. You can display the path of the configuration file currently used with the conf-get-{app-name} command. You can display this file in a cat fashion with the conf-show-{app-name} command. You can edit this file in vim by using the conf-edit-{app-name} command. The conf-list command provides the path to a set of sample configuration file you can use and modify.

conf-get-{app-name}​

Displays the path of the configuration file that is used to run the {app-name} application. You can set the path of the file by using the conf-set-{app-name} command. You can display this file in a cat fashion with the conf-show-{app-name} command. You can edit this file in vim by using the conf-edit-{app-name} command. The conf-list command provides the path to a set of sample configuration file you can use and modify.

conf-show-{app-name}​

Displays in a cat fashion the configuration file that is used to run the {app-name} application. You can get the path of the file by using the conf-get-{app-name} command. You can set the path of the file that is used by using the conf-set-{app-name} command. You can edit this file in vim by using the conf-edit-{app-name} command. The conf-list command provides the path to a set of sample configuration file you can use and modify.

conf-gen-{app-name}​

danger

This commands should be run as superuser.

A helper tool to generate the configuration files from templates. You can get the path of the file by using the conf-get-{app-name} command. You can display this file in a cat fashion with the conf-show-{app-name} command. You can edit this file in vim by using the conf-edit-{app-name} command. The conf-list command provides the path to a set of sample configuration file you can use and modify.

conf-edit-{app-name}​

danger

This commands should be run as superuser.

Opens the configuration file that is used when running the {app-name} application in vim in order to enable editing it. You can get the path of the file by using the conf-get-{app-name} command. The conf-list command provides the path to a set of sample configuration file you can use and modify. You can set the path of the file by using the conf-set-{app-name} command.