Configure ButConnect

ButConnect can be configured with simple configuration files.

Configuring Connections in Configure Mode

The easiest way to generate connection definitions in a configuration file is to use the configure mode:
Launch ButConnect.exe with the parameter ‘--configure’ or type ‘configure’ when prompted for a mode.
When you now — again — choose a mode, ButConnect will ask for all the necessary information for that use case as it would in normal interactive mode and write it to the desired .ini file and section.

To also configure more advanced options, replace ‘configure’ with ‘configall’.

Please also have a look at our configuration snippets page.

Configuration File Format

The ButConnect configuration file is in the .ini format and its default name is ‘butconnect.ini’.

As usual in .ini files, there are sections whose names are in square brackets.
Those sections group settings for specific connections or — if the name of a section is ‘default’ — settings for all connections. Settings that are placed above the first section are default settings, too.

Inside a section the individual settings for a particular connection are placed.
The settings are specified one per line. Option and value are separated by an equal sign (with or without white spaces).

If a setting is specified more than once, the last will come into effect. Most settings can be specified either on the command line or in a configuration file. Parameters from the command line have precedence over those from the config file.

Comments in a line start with a semicolon or a hash sign.

The previous format when the settings were specified exactly as they would on the command line, but one setting per line, with only a colon between option and value (no white spaces and not an equal sign as usual in .ini files) and including the leading dash (or dashes) is still supported.

The configuration file will be preserved when doing an update.

Here is an example:

#=====================================

[default]

	autoupdate

	port	= 443

#=====================================

[provide_postgres]

	mode	= target

	dest	= postgres.example.org

	loop	= 5432

#-------------------------------------

# The configuration to access that

# postgres endpoint could be ...

;[access_postgres]

;	mode	= source

;	orig	= 127.0.0.1

;	hook	= 5432

#=====================================

[access_webserver]

	local	= 80

#-------------------------------------

# The remote side could be ...

;[internal_webserver]

;	remote	= 8080

#=====================================

The desired configuration is selected by specifying it on the command line:
 (client)> ButConnect.exe -cn=internal_webserver

or — if the name of the config file differs:
  (agent)> ButConnect.exe -cf=example.conf -cn=access_webserver

In the interactive mode the connection can be selected by typing ‘cf’ or ‘cn’ when prompted for a mode and then giving the name of the configuration file and/or section.

Variables

In a configuration section of a .ini file, values of previously specified parameters can be referenced, for instance in the ‘param=’, ‘remoteport=’ or ‘localport=’ line by ‘$USER’, ‘${localhost}’, ‘%LocalPort%’ or ‘%rEmOtEpOrT’.

Additionally, new variables can be defined and used, e.g. ‘VNC=<path>’ and ‘start=$VNC’. Thus, even the configuration file can be quite platform independent — apart from those definitions.