ButConnect Documentation

Besides allowing to log into remote servers in a secure and encrypted way, the secure shell (SSH) protocol provides another great feature: TCP/IP port forwarding.
However, there are two issues that could prevent users from achieving benefit using port forwarding:

• You need an SSH server to connect to. If you have one in the desired network that is exposed to the Internet, you are able to connect to that network already and you can use port forwarding to reach hosts other than the SSH server itself.
• Even if you have that server waiting for your requests, the creation of port forwarding connections can be quite confusing.

ButConnect tries to improve this situation and makes it easier to actually use that facility ...

Different Functionalities of ButConnect

Default Mode

• With ButConnect, you don't need an SSH server for every single network you want to connect to. Instead, you can use a server that the ButConnect service provides.
  (In addition, a ButConnect session on both client and agent host is — in terms of TCP/IP — always a client connection from your location to the ButConnect server. There is no need to expose any part of your network to the Internet.)
  
• Besides the fact that in the first place ButConnect enables you to connect to the other side, it also makes it easy to reach hosts in the remote network other than the connected host itself by arranging the appropriate port forwarding.

Direct Mode

• Even in case your customer has an SSH server running on his network, the use of ButConnect is still helpful to simplify the creation of SSH port‑forwarding connections (... just like the equivalent feature in default mode).
• Without having to configure every single one on the remote side, ButConnect's direct mode brings many more devices within reach.

Mixed Mode

• Both default and direct mode can also be used in combination:
  If there's no SSH server accessible via the Internet, a connection in default mode to an internal one could take on the role to provide access to an SSH server that, in turn, can be used to access any other host or service on the remote network in ButConnect's direct mode.
• In the simplest and most straightforward case, that internal SSH server could be the device running ButConnect itself (for instance, the ButConnect Appliance — basically an Orange Pi or Raspberry Pi configured for unattended connections and then simply attached to your network).

Different Ways to Control ButConnect

There are different ways to control ButConnect:

• Interactively
• Non-interactively
  • via command line
  • via configuration file
  • via environment variables

Interactive Mode

The easiest way for starting to work with ButConnect is to use its interactive mode. Just launch the executable ButConnect.exe and follow the instructions.

Without any argument ButConnect will run fully interactive. You have to choose the mode of operation first.
All possible modes are divided into two different groups to choose from depending on whether the user wants or needs to receive (client modes) or to provide remote support (agent modes).

The available client modes for receiving remote support are:

• ‘c’ or ‘client’ for default ‘client mode’
  The default client mode is the most simple mode. The user (the one who needs remote support) just launches the executable ButConnect.exe and presses [Return]. With a little help from his agent he will be able to start this mode even if he is not very familiar with the computer he is working on.
  
  
• ‘ca’ for ‘chat to agent’
  For security reasons, every connection regarding to ButConnect has to be initiated by the client. This is also true for the chat. If the person who can provide help wants to initiate a chat to the client, he needs to start the chat session. For this session he slips into the client role.
  
  
• ‘d’ or ‘download’ for ‘download mode’
  The download mode allows to transfer a file from the agent to the client. This action is initiated by the client, too. It is not necessary to establish a remote access session first. After the file is transferred, the connection is terminated automatically.
  
  
• ‘r’ or ‘remote’ for ‘remote mode’
  In contrast to the default client mode, the remote mode does not force the port on the client side (5900) to connect to a VNC server. The port can be chosen to meet the requirements of the intended connection. This mode is called ‘remote’ because the client side of the connection is the remote end in relation to the remote access session.
  
  
• ‘t’ or ‘target’ for ‘target mode’
  In target mode it is possible to connect to some other host or service in the clients network: the target host for this session.
  
  
• ‘la’ for ‘let access’
  If there is an SSH server that you can connect to on the remote side, you can allow the remote side to access a service that is running on your side without using an SSH server provided by the ButConnect service. This mode is for establishing the required connection and to arrange the appropriate port forwarding.
  
  

The available agent modes for providing remote support are:

• ‘a’ or ‘agent’ for default ‘agent mode’
  The agent can run ButConnect in interactive mode, too. For that, he launches ButConnect.exe without any argument and presses [A] (or ‘agent’) and then [Return]. After entering the credentials that he received from the client, the connection will be established and the agent is able to access the client's computer.
  
  
• ‘ac’ for ‘accept to chat’
  To accept a chat request from the client, the agent chooses the ‘accept to chat’ mode and enters the credentials provided by the client.
  
  
• ‘u’ or ‘upload’ for ‘upload mode’
  To upload files and to place them on the client's computer is only allowed after the client shared the credentials with the agent.
  
  
• ‘l’ or ‘local’ for ‘local mode’
  While the default client and agent modes try to be as simple as possible, the remote and local mode provide several choices to establish more universal connections.
  
  
• ‘s’ or ‘source’ for ‘source mode’
  Not only connections from the agent's host to the client's host are possible, but also connections from some other host in the agent's network to some host in the client's network. The ‘source’ is the IP address of the interface that's connected to the agent's LAN.
  
  
• ‘ga’ for ‘get access’
  If there is an SSH server that you can connect to on the remote side, you don't need to use one that is provided by the ButConnect Service. This mode is for connecting to such a server directly and to arrange port forwarding in an easy way.
  
  
• ‘px’ or ‘proxy’ for ‘proxy mode’ (dynamic forwarding)
  In this mode ButConnect acts as a SOCKS5 proxy. Configure your application to use this proxy and access the hosts in the remote network by their real IP addresses.
  (For RealVNC set:
  param = "proxyserver=socks://$PROXYHOST:$PROXYPORT"
  and for Chromium:
  param = "--proxy-server=socks5://$PROXYHOST:$PROXYPORT"
  in butconnect.ini to use the proxy.)

Non-interactive Modes

If you already know what you're doing, it's faster to use one of the non-interactive modes. This way, you also can automate the process of establishing connections.

Controlled via Command Line

To tweak the behavior for a connection that is used in a script or only once you can specify the appropriate settings on the command line.

Controlled via Config File

Most settings can also be placed in a configuration file. Default settings (those that are placed in the ‘default’ section or in front of the first section) are used for all connections, but if you place your settings in a section that defines a specific connection, they have an effect only if you establish that particular connection.

Controlled via Environment Variables

And finally, the operation of ButConnect can be controlled by environment variables. These are named exactly as the parameters for command line or config file, but prefixed with ‘BUTCONNECT_’.