Usage - JS-Produksiyon/pulsar GitHub Wiki

Pulsar is very easy to use and shouldn't need much explanation. But there are a few minor points that IT personnel should be aware of in usage. This document goes over the steps that are necessary to make the software work, as well as some tips and tricks for it to work better.

Preparation for First Run

Before Pulsar can be used, a valid Nebula .yaml configuration file must be prepared and the necessary CA, user private key and certificate files must be generated. The method for doing this is described in Setting Up Nebula Credentials. Two important points must be made regarding directory structure.

  1. Pulsar assumes that the CA, user private key and certificate files are located in the same directory (folder) as the .yaml configuration file and that the references to the files in the configuration file are relative. Pulsar, therefore, navigates to the directory (folder) containing the configuration file before starting Nebula.

  2. If the CA and keys are to be in a different location, the .yaml configuration file needs to be configured with exact paths to the CA, user private key and certificate files.

Optionally, the IT department can provide a hosts file containing IP Address / Hostname pairs for the user to more easily access resources on the Nebula mesh network. The formatting directives for this file are found in Configuring a Valid HOSTS File.

We recommend placing the credentials in a directory (folder) relative to the location of the Pulsar executable (or repository directory). On Windows this structure would look something like this:

pulsar/
   |-- _internal/
   |        |-- pulsarhosts.txt
   |        |-- settings.yaml
   |
   |-- credentials/
   |        |-- ca.crt
   |        |-- config.yaml
   |        |-- hosts.txt
   |        |-- user.crt
   |        |-- user.key
   |
   |-- pulsar.exe

On MacOS the configuration files are stored in /Users/[username]/Library/Application Support/Pulsar. These can be manually erased using Finder, if necessary. The credential files can be placed anywhere the user desires.

Superuser Requirement

Because the Nebula client needs to have superuser access to set up the networking connection, Pulsar also runs in superuser mode. This means that in Windows a UAC prompt will pop up when running the program. On MacOS, the user will be prompted to enter their user password to run the software.

First Run

On the first run of Pulsar, the program will pop up a reminder to set the configuration file. Only when this is done can you change any other settings, like the interface language.

Screenshot of First run

Once the configuration file is defined, the Connect to Nebula Mesh Network button will activate and Pulsar can connect to Nebula.

On MacOS you will be required to shut down and restart Pulsar after defining the configuration file so that it can run in the required superuser mode.

Regular Usage

Pulsar normally starts up minimized, with only the Pulsar network disconnected icon showing in the System Tray (Windows) or menu bar (MacOS).

Pulsar disconnected in System Tray

When connected the icon looks like this::

Pulsar connected in System Tray

Most important functionality can be accessed by right-clicking the Pulsar icon in the System Tray or menu bar and selecting the menu items there. These are as follows:

  • Connect to Nebula > Opens a connection to the mesh network
  • Disconnect from Nebula > Closes the connection to the mesh network
  • Show Pulsar Window > Opens the Pulsar window
  • Quit > Closes down Pulsar

In Windows a console window may open detailing the connection status of the Nebula network. This is expected behavior and the detail of the content displayed here can be controlled by options in the Nebula configuration file.

The Pulsar window looks as follows:

Pulsar Window

  • To connect to the Nebula network, click the big green button or Connect in the File menu, or else right-click the icon in the system tray or menu bar and select Connect to Nebula.

  • To disconnect from the Nebula network, click the big red button or Disconnect in the File menu, or else right-click the icon in the system tray or menu bar and select Disconnect from Nebula.

Pulsar will not quit if the Pulsar window is closed. It can only be shut down by either using the Quit command from the System Tray or menu bar or else by clicking the Quit Pulsar or selecting File > Quit from the menu. If Pulsar is still connected when being quit, a warning will display.

Settings

Nebula Configuration File

On MacOS this setting can only be changed if the application is not running in superuser mode. The application will prompt the user to shut down and restart in regular user mode if in superuser mode.

Pointing to the Nebula configuration file is required for Pulsar to work. This can either be done by using the Open... button and navigating to the location of the .yaml file or else by inputting the path for the file. Pulsar will validate the file upon clicking Save Settings.

In Windows a / rather than a \ may be shown as a directory separator. This is expected behavior and does not impede the running of Pulsar.

Interface Language

Select the available interface language from the dropdown. Clicking Save Settings will automatically switch the entire interface to the selected language.

It is not possible to change the interface language if a Nebula configuration file has not been defined!

Start in system tray only

If this box is checked, Nebula will only start in the System Tray or Menu bar. This keeps the application from cluttering up the rest of the interface.

Connect to Nebula Network on Startup

If this option is selected, Pulsar connects to the Nebula network immediately on startup. This is great for running Pulsar on computers or servers that need to provide immediate access to the network resources.

Register Nebula network hosts locally

Checking the Register Nebula network hosts locally box will cause Nebula to add items listed in a defined hosts file to the system's hosts file, allowing users to access various network hosts using fully qualified domain names rather than IP addresses. These entries are deleted from the hosts file when Pulsar disconnects from the Nebula network.

The hosts to add are defined by clicking the Configure... button, at which point a window will pop up that allows you to select a hosts file using the Open... button, enter a path to a text file containing the hosts file, or enter the entries into a text box.

On MacOS the hosts configuration window can only be accessed if the application is not running in superuser mode. The application will prompt the user to shut down and restart in regular user mode if in superuser mode.

Pulsar hosts configuration window

If a file is selected, the valid comment lines and IP Addres / hostname pairs will be listed in the text box for verification. At this point the user can either choose to import the file as is by selecting the File radio button, or make changes and use the content in the text box by selecting the IP Address / Hostname Pairs radio button.

Once the OK button is clicked, the configuration data for the hosts file will be loaded into memory, but it will only be saved once the Save Settings button is clicked on the main Pulsar screen.

If you make these changes while connected to the Nebula network, you will have to disconnect and reconnect to the network before Pulsar will make the changes to your computer’s hosts file.

If the Settings Get Messed Up

This is obsolete as of v.1.0.1 as Pulsar now will simply recreate the settings.yaml file if it is messed up, returning to the First Run experience.

If the settings get messed up, Pulsar can very easily be reset by deleting the pulsar/_internal/settings.yaml and pulsar/_internal/pulsarhosts.txt files.

pulsarhosts.txt can still be manually deleted, though, if the user so desires. It is in the pulsar/_internal directory (folder) on Windows or in /Users/[username]/Library/Application Support/Pulsar on MacOS.

pulsarhosts.txt only exists if you have saved the hosts entries from the text box.

Issues with Pulsar on MacOS on M-series chips

This has been resolved with Pulsar v.1.0.2

Because of limitations in PyQT, the following functions do not work on Macs that have an M1 chip in them.

  • The open file dialog boxes (Open... buttons) does not work at all. Interface beachballs for about a minute.
  • Pasting into input boxes does not work.

Pulsar will work if the full path to the .yaml configuration file is typed into the Neblua Configuration File box. The hosts will also work if the hosts entries are typed in by hand. Tedious, yes. We will revisit these bugs.

Previous Page: Installation

Nexg Page: Setting up Nebula Credentials

Last Updated: 2024-06-28