Skip to content

Command Line

Jump to bottom
albertony edited this page Dec 7, 2020 · 4 revisions

Using Barrier from the Command Line

You might to use the command line without the GUI to run barrier, especially if you do not change settings frequently or do not want the Qt GUI running all the time. These instructions cover using Barrier via the command line interface.

The Synergy wiki was used as a reference in creating this documentation.

Document Conventions

  • Text in angle brackets <text> is input supplied by the user
  • Text in square brackets [text] represents optional inputs
  • Text in curly braces with pipes {true|false} represents options to choose from
  • Text in italics are user interface elements or items on-screen
  • Text in a monospaced font are keyboard shortcuts, prompts, commands, or command output

Topics

Windows

To use Barrier commands from the command line in Windows you can either change directories to the folder that they are located in each time or add the Barrier directory to your %PATH% variable.

To change to the directory:

cd "\Program Files\Barrier"

To add the directory to %PATH%:

  • Press (⊞ Win) + Break to view the System control panel
  • Click on Advanced system settings on the left panel
  • On the Advanced tab, click the Environment Variables... button
  • In the System variables list, double-click the Variable named Path
  • Click New and enter C:\Program Files\Barrier
  • Click OK in the Edit environment variable dialog
  • Click OK in the Environment Variables dialog
  • Click OK in the System Properties dialog

This will only effect command prompts opened after the change.

Portable

The command line version of Barrier is a single client executable barrierc.exe and a single server executable barriers.exe. They both have a dependency to OpenSSL libraries, libeay32.dll and ssleay32.dll (used for encryption with argument --enable-crypto), as well as Microsoft Visual C++ runtime libraries.

From an existing installation you can copy the necessary program files to a location of choice, to get a command line only portable (depending on configuration) installation. Copy the following files from the installation directory C:\Program Files\Barrier:

barrierc.exe
barriers.exe
libeay32.dll
ssleay32.dll

To be able to generate server certificate, you can also choose to include the OpenSSL application itself (on the server), together with Barrier's predefined OpenSSL configuration file:

openssl.exe
barrier.conf

As long as you have the Microsoft Visual C++ Redistributable for Visual Studio 2019 installed (or copy the necessary runtime libaries msvcp140.dll, vcruntime140.dll and vcruntime140_1.dll into the application directory), you will now have a stand-alone application directory that you can manually copy into computers where you need it.

For a completely portable installation, with local configuration, you must configure the location of server configuration file and SSL/TLS configuration files. See Text File Configuration, Server Command Line Options, Client Command Line Options and SSL/TLS Configuration, below.

Back to top

MacOS

To use Barrier commands from the command line on MacOS you can either change directories to the folder they are located and run them using the relative path (i.e. ./barriers) each time or add the Barrier.app/Contents/MacOS directory to your $PATH.

cd /Applications/Barrier.app/Contents/MacOS/

To add the directory to $PATH:

export PATH=/Applications/Barrier.app/Contents/MacOS/:$PATH

The $PATH variable will only be set for the duration of the current shell session. To make the path persistent, add it as a new line in the /etc/paths file or set the $PATH variable in your .profile or .bashrc file.

Back to top

Linux/Unix

If Barrier has been installed using a package manager or equivalent it should already be in your $PATH.

If installed using flatpak, you can run the command line client like this:

flatpak run --command=barrierc com.github.debauchee.barrier

And server like this:

flatpak run --command=barriers com.github.debauchee.barrier

Back to top

Server Command Line Options

To see the server command line options, use the --help argument:

barriers --help
Start the barrier server component.

Usage: barriers [--address <address>] [--config <pathname>] [--daemon|--no-daemon] [--name <screen-name>] [--restart|--no-restart] [--debug <level>]

Options:
  -a, --address <address>  listen for clients on the given address.
  -c, --config <pathname>  use the named configuration file instead.
  -d, --debug <level>      filter out log messages with priority below level.
                             level may be: FATAL, ERROR, WARNING, NOTE, INFO,
                             DEBUG, DEBUG1, DEBUG2.
  -n, --name <screen-name> use screen-name instead the hostname to identify
                             this screen in the configuration.
  -1, --no-restart         do not try to restart on failure.
      --restart            restart the server automatically if it fails. (*)
  -l  --log <file>         write log messages to file.
      --no-tray            disable the system tray icon.
      --enable-drag-drop   enable file drag & drop.
      --enable-crypto      enable the crypto (ssl) plugin.
      --profile-dir <path> use named profile directory instead.
  -f, --no-daemon          run in the foreground.

Back to top

Client Command Line Options

To see the client command line options, use the --help argument:

barrierc --help
Start the barrier client and connect to a remote server component.

Usage: barrierc [--yscroll <delta>] [--daemon|--no-daemon] [--name <screen-name>] [--restart|--no-restart] [--debug <level>] <server-address>

Options:
  -d, --debug <level>      filter out log messages with priority below level.
                             level may be: FATAL, ERROR, WARNING, NOTE, INFO,
                             DEBUG, DEBUG1, DEBUG2.
  -n, --name <screen-name> use screen-name instead the hostname to identify
                             this screen in the configuration.
  -1, --no-restart         do not try to restart on failure.
      --restart            restart the server automatically if it fails. (*)
  -l  --log <file>         write log messages to file.
      --no-tray            disable the system tray icon.
      --enable-drag-drop   enable file drag & drop.
      --enable-crypto      enable the crypto (ssl) plugin.
      --profile-dir <path> use named profile directory instead.
  -f, --no-daemon          run in the foreground.
      --daemon             run as a daemon. (*)

Back to top

Creating a systemd service (Linux)

If you would like to add the barrier client or server as a service on a systemd-based linux distribution, you can create a .service file for systemd.

Running Barrier as a systemd service as the root user will allow Barrier to access any X11 screen. If you need to use Barrier before logging (i.e. in a Display Manager like GDM) in this is possibly the only option despite the possible security concern of running Barrier as root. If you do not need to use Barrier at the login screen it is likely better to run Barrier under your user account.

Here is an example .service template for a service on a computer used by one person where Barrier does not need access to the Display Manager. This can be put in the /etc/systemd/system/ directory and started or stopped with the systemctl command. This assumes that the X11 display is on :0.

[Unit]
Description=Barrier Client daemon
After=network.target

[Service]
User=<username>
Group=<groupname>
ExecStart=barrierc --enable-crypto --display :0 --debug INFO -f <server hostname or IP>
Restart=always

[Install]
WantedBy=multi-user.target

If you want to use a systemd Barrier service on a multi-user system, consider using a user service or starting the GUI application at logon instead.

The barrier client can also be started from the command line remotely using ssh as long as $DISPLAY is set or specified with --display.

Back to top

Launchd daemon (MacOS)

If you want to create a daemon for MacOS instead of using the GUI, you can create a daemon/agent using a .plist file in ~/Library/LaunchAgents. Information about creating daemons/agents for MacOS can be found at launchd.info.

The recommended method of starting automatically on MacOS is with the GUI by dragging Barrier.app to the Login Items pane in System Preferences > Users & Groups. This method does start Barrier after logging in.

Back to top

Windows Service

The Windows version uses a service that can be started/stopped in the Windows Services snap-in. The Services snap-in can be accessed by pressing (⊞ Win) + R and typing services.msc in the Run dialog. The service is named Barrier.

Back to top

Text File Configuration

If you use Barrier from the command line you may need to create a configuration file. Configuration files can be copied from their default GUI locations as a baseline.

The client will use the configuration specified by the server.

By default the server will look for a configuration file at the following paths, in prioritized order:

  • User specific location: %LocalAppData%\Barrier\barrier.sgc on Windows, ~/.local/share/barrier/.barrier.conf or $XDG_DATA_HOME/barrier/.barrier.conf on Linux.
  • System shared location: C:\ProgramData\Barrier\barrier.sgc on Windows, /etc/barrier.conf on Linux.

The user specific location can be customized with command line argument --profile-dir, and Barrier will look for a configuration file with default name (barrier.sgc on Windows, .barrier.conf on Linux) there:

barriers --profile-dir ~/barrier/config/path ...

You can also use command line argument --config to set path to a specific configuration file that should be used.

barriers --config ~/barrier/config/path/file.conf ...

Back to top

Server Configuration File

The text file configuration uses four different sections; screens, aliases, links and options. The structure of a server configuration file looks something like this:

section: screens
    hostname1:
        setting = value
    hostname2:
        setting = value
end
section: aliases
    hostname1:
        hostname1.alias
    hostname2:
        hostname2.alias
end
section: links
    hostname1:
        direction = hostname2
    hostname2:
        direction = hostname1
end
section: options
    option = value
end

Examples can be found in the doc directory of the Barrier repository.

Back to top

Screen Options

By default screens use the hostname of the server or client. Each screen may have any of the following settings:

halfDuplexCapsLock = {true|false}
halfDuplexNumLock = {true|false}
halfDuplexScrollLock = {true|false}
switchCorners = {none, top-left, top-right, bottom-left, bottom-right, left, right, top, bottom, all}
switchCornerSize = N
xtestIsXineramaUnaware = {true|false}
preserveFocus = {true|false}
shift = {shift|ctrl|alt|meta|super|none}
ctrl = {shift|ctrl|alt|meta|super|none}
alt = {shift|ctrl|alt|meta|super|none}
altgr = {shift|ctrl|alt|meta|super|none}
meta = {shift|ctrl|alt|meta|super|none}
super = {shift|ctrl|alt|meta|super|none}
  • halfDuplexCapsLock, halfDuplexNumLock, and halfDuplexScrollLock are for clients that use a press to enable and a release to disable instead of toggling with a press and release
  • switchCorners prevents switching when reaching the edge of any of the listed corners
  • switchCornerSize is the size in pixels to ignore on a screen edge when using switchCorners
  • xtestIsXineramaUnaware works around a bug when using certain versions of the XTest extension in combination with Xinerama on X11 clients (Linux)
  • preserveFocus prevents dropping focus of the current window when switching screens
  • shift, ctrl, alt, altgr, meta, and super allow these keys to be mapped to a different key for that screen

Back to top

Aliases

By default a screen name is the hostname of the client or server. However, the screen name can be specified on the command line for both the server and client with the --screen option and if there is a matching Alias it will be recognized. Aliases must be unique.

Back to top

Links

The links section describes the screens relationships to each other. Links allow you to specify how screens are layed in relation to each other. Links use the following format:

{left|right|up|down}(<range>) = name(<range>)

Each link defines a screen edge and the screen name it connects to. The range is an optional percentage (between 0 and 100) of the edge that will connect to the other screen. For example, if there are two hosts on the right of host1 and they are split 50-50 on the right edge, the configuration might look something like this:

section: links
    host1:
        right(0,50) = host2(50,100)
        right(50,100) = host3(0,50)
...

Overlaps on the screen ranges are not supported.

A simpler configuration with two hosts might look like this:

section: links
    host1:
        right = host2
    host2:
        left = host1

The GUI can be used to set up the layout and the configuration can be copied into the configuration file being used for the command line.

Back to top

Options

The key/value pairs in the options section are global options that apply to all screens.

heartbeat = N
switchCorners = {none, top-left, top-right, bottom-left, bottom-right, left, right, top, bottom, all}
switchCornerSize = N
switchDelay = N
switchDoubleTap = N
screenSaverSync = {true|false}
relativeMouseMoves = {true|false}
clipboardSharing = {true|false}
clipboardSharingSize = N
win32KeepForeground = {true|false}
keystroke(key) = actions
mousebutton(button) = actions
  • heartbeat disconnects clients if they do not send a message within N milliseconds
  • switchCorners prevents switching screens when reaching the edge on any of the listed corners
  • switchCornerSize is the size in pixels to ignore on a screen edge when using switchCorners
  • switchDelay prevents switching unless the mouse rests on the edge for N milliseconds
  • switchDoubleTap prevents switching unless the edge is double-tapped within N milliseconds
  • screenSaverSync will sync the screensavers if set to true. If set to false the clients will use their own screensaver settings and the server screensaver won't start as long as there is input to any screen
  • relativeMouseMoves causes clients to move the mouse using relative coordinates rather than absolute when the cursor is locked to a screen. This is may assist with certain games
  • clipboardSharing enables sharing clipboard contents between server and clients if set to true
  • clipboardSharingSize sets a limit of N Kb of data when clipboard sharing is enabled
  • win32KeepForeground grabs the focus of on a Windows server on switching to a client if set to true. If set to false it will leave the current window in the foreground. Leaving this setting on true avoids issues with other apps interfering with reading hardware inputs
  • keystroke can be used to bind actions to keys
  • mousebutton can be used to bind a modifier and a mouse button (left is 1, middle is 2, and right is 3) to an action.

Back to top

Actions

Back to top

Keys

Keys can be in either unicode hexadecimal format (i.e. \uXXXX) or a valid key name. The following named keys are valid in a configuration:

Standard Keys Standard Keys Keypad Keys Media Keys Web Keys
F1 to F35 Left KP_0 to KP_9 AppMail WWWBack
Ampersand LeftTab KP_F1 to KP_F4 AppMedia WWWFavorites
Apostrophe Less KP_Add AppUser1 WWWForward
Asterisk Linefeed KP_Begin AppUser2 WWWHome
At Menu KP_Decimal AudioDown WWWRefresh
BackSpace Minus KP_Delete AudioMute WWWSearch
Backslash NumLock KP_Divide AudioNext WWWStop
Bar Number KP_Down AudioPlay
Begin PageDown KP_End AudioPrev
BraceL PageUp KP_Enter AudioStop
BraceR ParenthesisL KP_Equal AudioUp
BracketL ParenthesisR KP_Home Eject
BracketR Pause KP_Insert
Break Percent KP_Left
Cancel Period KP_Multiply
CapsLock Plus KP_PageDown
Circumflex Print KP_PageUp
Clear Question KP_Right
Colon Redo KP_Separator
Comma Return KP_Space
Delete Right KP_Subtract
Dollar ScrollLock KP_Tab
DoubleQuote Select KP_Up
Down Semicolon
End Slash
Equal Sleep
Escape Space
Exclaim Space
Execute SysReq
Find Tab
Grave Tilde
Greater Underscore
Help Undo
Home Up
Insert

Back to top

Client Configuration File

Client options are set either by the command line arguments or by the server the client has connected to. There is no --config argument for the barrierc client command.

The client saves a configuration file that can be read for informational or troubleshooting purposes, and is structured like an .ini file. It has two sections, [General] and [internalConfig].

Back to top

SSL/TLS Configuration

Barrier supports SSL/TLS encryption, by use of the OpenSSL library (included). This must be anabled with command line argument --enable-crypto, and requires a certificate and fingerprint to be configured.

The SSL related configuration is kept in subdirectory "SSL" in the same user specific location as the text file configuration is loaded from: By default %LocalAppData%\Barrier\SSL on Windows, ~/.local/share/barrier/SSL or $XDG_DATA_HOME/barrier/SSL on Linux, but configurable with command line argument --profile-dir.

On the server, the root of the SSL directory must contain the certificate as a file with name Barrier.pem, containing the private and public key.

Barrier uses fingerprints to validate that a malicious server is not trying to intercept a client connection. A server's fingerprint must be generated from the certificate, and may be kept in file SSL/Fingerprints/Local.txt on the server. All clients must have the fingerprint hash string of trusted servers in a file SSL/Fingerprints/TrustedServers.txt. When connecting to a server, if it presents a fingerprint not explicitely trusted by the client, it will refuse the connection. See also Fingerprint trust troubleshooting.

The server will therefore typically contain the following files:

/SSL/Barrier.pem
/SSL/Fingerprints/Local.txt

Clients must contain the following file:

/SSL/Fingerprints/TrustedServers.txt

Generating certificate and fingerprint

The main UI application has built-in functionality to generate a self-signed server certificate, and fingerprint. In a command line only (portable) environment you will have to create these manually, using the OpenSSL command line utility, which is included in a Barrier installation together with a Barrier specific OpenSSL configuration file barrier.conf. To create them the same way as the UI application does, you can follow the following Windows example. It uses openssl.exe and barrier.conf from a Barrier installed in C:\Program Files\Barrier, generating configuration in %LocalAppData%\Barrier\SSL. If you have the OpenSSL files in a different location and/or are planning to keep the SSL files in a custom location specified with command line argument --profile-dir, you must change the paths in the example accordingly.

mkdir "%LocalAppData%\Barrier\SSL\Fingerprints" >NUL 2>&1
set OPENSSL_CONF=C:\Program Files\Barrier\barrier.conf
SET RANDFILE=%LocalAppData%\Barrier\SSL\.rnd
"C:\Program Files\Barrier\openssl.exe" req -x509 -nodes -days 365 -subj /CN=Barrier -newkey rsa:2048 -keyout "%LocalAppData%\Barrier\SSL\Barrier.pem" -out "%LocalAppData%\Barrier\SSL\Barrier.pem"
IF EXIST "%RANDFILE%" DEL "%RANDFILE%"
"C:\Program Files\Barrier\openssl.exe" x509 -fingerprint -sha1 -noout -in "%LocalAppData%\Barrier\SSL\Barrier.pem" > "%LocalAppData%\Barrier\SSL\Fingerprints\Local.txt"

Now, on any clients you must manually create the %LocalAppData%\Barrier\SSL\Fingerprints\TrustedServers.txt file, with the hash from the server's %LocalAppData%\Barrier\SSL\Fingerprints\Local.txt.

Given the server's Local.txt contains:

SHA1 Fingerprint=96:32:AB:DD:38:5C:E5:21:20:8E:52:E8:83:28:A0:2A:CC:CC:8F:A3

You must put the following into the client's TrustedServers.txt:

96:32:AB:DD:38:5C:E5:21:20:8E:52:E8:83:28:A0:2A:CC:CC:8F:A3
Clone this wiki locally