Azure
/
azure-relay-bridge
зеркало из https://github.com/Azure/azure-relay-bridge.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность
azure-relay-bridge/CONFIG.md

15 KiB
Исходник Ответственный История

Configuration and Command Line Options

Command Line Options

'azbridge' can be run in a "local" or "remote" mode. The "local" mode binds a local listener address or socket to a relay name. The "remote" mode binds a relay name to a remote listener adress.

Since azbridge helps with scenarios not dissimilar to SSH tunnels, albeit without requiring peer-to-peer connectivity, the command line syntax of 'azbridge' uses elements that resemble SSH's equivalent tunnel functionality, especially the -L and -R arguments. The key difference to SSH is that azbridge always binds sockets to an Azure Relay name, and that Azure Relay acts as the identifier for the tunnel and as network rendezvous point. In other words, you always need to pair an azbridge instance running as local forwarder with an azbridge running as a remote forwarder on the other end.

SSH's dynamic SOCKS proxy functionality (SSH's -D option) is not supported since it puts clients in control of selecting remote hosts after they've been bridged into a foreign network, and this may pose significant security risks and might inadvertently enable undesired access to resources on that foreign network.

(C) -- 127.3.2.1:5000 -> (L) -- ['myname'] -> (R) -- 10.1.2.3:5000 -> (S)

  • (C) Client
  • (L) Local forwarder: azbridge -L 127.3.2.1:5000:myname
  • (R) Remote forwarder: azbridge -R myname:10.1.2.3:5000
  • (S) Server listening at 10.1.2.3:5000

A single instance of azbridge can support multiple concurrent "local" listeners and multiple "remote" forwarders concurrently, also in a mixed configuration.

The required Azure Relay connection string can either be supplied on the command line, can be picked from an environment variable, or from a configuration file.

The connection string's embedded authentication/authorization information must confer sufficient permissions for the desired operation(s) to be executed, e.g. for the "local" mode, the connection string must enable the bridge to send to the configured relay entity.

Arguments:

-b bind_address

Use bind_address on the local machine as the source address of forwarding connections. Only useful on systems with more than one address.

-C

Requests compression for the tunnel. The compression algorithm is the same used by gzip(1), and the "level" can be controlled by the CompressionLevel configuration option. Compression is desirable on slow connections, but may cause significant throughput and other performance issues on fast networks. The default value can be set on a host-by-host basis in the configuration files; see the Compression configuration option.

-D

Reserved. Not presently supported

-E endpoint_uri

Azure Relay endpoint URI (see -x).

-F configfile

Specifies an alternative per-user configuration file. If a configuration file is given on the command line, the system-wide configuration file (Linux: /etc/azbridge/azbridge_config.machine.yml, Windows: %ALLUSERSPROFILE%\Microsoft\AzureBridge\azbridge_config.machine.yml) will be ignored.

The default for the per-user configuration file is ~/.azurebridge/config on Linux and %USERPROFILE%.azurebridge\config on Windows.

-g

Allows remote hosts to connect to local forwarded ports.

-K policy_name

Azure Relay shared access policy name to use (see -x).

-k policy_key

Azure Relay shared access policy key to use (see -x).

-L [bind_address:]port:relay_name
-L local_socket:relay_name

Specifies that connections to the given TCP port or Unix socket on the local (client) host are to be bound (forwarded) to the given Azure Relay name. This works by allocating a socket to listen to either a TCP port on the local side, optionally bound to the specified bind_address, or to a Unix socket*. Whenever a connection is made to the local port or socket, the connection is forwarded to a connected remote bridge via the chosen Relay entity.

Port forwardings can also be specified in the configuration file. Only the superuser can forward privileged ports. IPv6 addresses can be specified by enclosing the address in square brackets.

By default, the local port is bound in accordance with the GatewayPorts configuration setting. However, an explicit bind_address may be used to bind the connection to a specific address. The bind_address of ``localhost'' indicates that the listening port be bound for local use only, while an empty address or '*' indi- cates that the port should be available from all interfaces.

The -L option can be used multiple times on a single command line.

-o option

Can be used to give options in the format used in the configura- tion file. This is useful for specifying options for which there is no separate command-line flag.

-q

Quiet mode. Causes most warning and diagnostic messages to be suppressed.

-R relay_name:port
-R relay_name:host:hostport
-R relay_name:local_socket

Specifies that connections to the given Azure Relay name are to be forwarded to the given host and port, or Unix socket*, on the local side. Whenever a connection is made to the Relay, the connection is forwarded to this listener (or a concurrently connected listener in a random load distribution fashion), and a then a forwarding connection is made to either port, host:hostport, or local_socket, from the local machine.

Port forwardings can also be specified in the configuration file. Privileged ports can be forwarded only when logging in as root.
IPv6 addresses can be specified by enclosing the address in square brackets.

The -R option can be used multiple times on a single command line.

-S signature

Azure Relay shared access signature (previously issued access token) to use (see -x)

-V

Display the version number and exit.

-v

Verbose mode. Causes ssh to print debugging messages about its progress. This is helpful in debugging connection, authentica- tion, and configuration problems. Multiple -v options increase the verbosity. The maximum is 3.

-x connection_string

Connection String. Azure Relay connection string for the namespace or for a specific Azure Relay. The Connection String properties can be overriden by the -E (Endpoint), -K (SharedAccessKeyName), -k (SharedAccessKey), -S (SharedAccessSignature) arguments.

If an EntityPath is specified in the connection string, that name is the only valid option for the relay_name expressions in the -L and -R options or for expressions in the effective configuration file.

The connection string can be set via the AZURE_BRIDGE_CONNECTIONSTRING environment variable.

Configuration File

The configuration file is a YAML file that specifies options that apply to the machine or user. The machine level options are always read and then complemented by or overriden by the user-level options.

The configuration file can exist in three locations:

  1. Machine configuration, always loaded if present. Linux: /etc/azurebridge/azurebridge_config Windows: %ALLUSERSPROFILE%\Microsoft\AzureBridge\azbridge_config
  2. User configuration, overrides and complements machine config. Linux: ~/.azurebridge/config Windows: %USERPROFILE%.azurebridge\config
  3. Override user configuration location for current execution with the -f option.

The configuration file holds a range of configuration options that, just like the command line options, partially lean on similar expressions used in SSH, even though the configuration format differs from that of SSH.

The "LocalForward" and "RemoteForward" sections define bindings as with the -L and -R command line options above.

  • AddressFamily - Specifies which address family to use when connecting. Valid arguments are "any", "inet" (use IPv4 only), or "inet6" (use IPv6 only). The default is "any".
  • AzureRelayConnectionString - Azure Relay connection string for a Relay namespace. Only one namespace connection string can be specified per configuration file.
  • AzureRelayEndpoint - Azure Relay endpoint URI for a Relay namespace. Overrides the 'Endpoint' property of the connection string, if present.
  • AzureRelaySharedAccessKeyName - Azure Relay shared access policy name. Overrides the 'SharedAccessKeyName' property of the connection string, if present.
  • AzureRelaySharedAccessKey - Azure Relay shared access policy key. Overrides the 'SharedAccessKey' property of the connection string, if present.
  • AzureRelaySharedAccessSignature - Azure Relay shared access policy signature. Overrides the 'SharedAccessSignature' property of the connection string, if present.
  • BindAddress - Use the specified address on the local machine as the source address of the connection. Only useful on systems with more than one address.
  • ClearAllForwardings - Specifies that all local, and remote port forwardings specified in the configuration files or on the command line be cleared. This option is primarily useful when used from the command line to clear port forwardings set in configura- tion files. The argument must be "true" or "false". The default is "false".
  • Compression - Specifies whether to use compression. The argument must be "true" or "false". The default is "false".
  • CompressionLevel - Specifies the compression level to use if compression is enabled. The argument must be an integer from 1 (fast) to 9 (slow, best). The default level is 6, which is good for most applications.
  • ConnectionAttempts - Specifies the number of tries (one per second) to make before exiting. The argument must be an integer. This may be useful in scripts if the connection sometimes fails. The default is 1.
  • ConnectTimeout - Specifies the timeout (in seconds) used when connecting to the relay server, instead of using the default system TCP timeout. This value is used only when the target is down or really unreachable, not when it refuses the connection.
  • ExitOnForwardFailure - Specifies whether azbridge(1) should terminate the connection if it cannot set up all requested local, and remote port forwardings, (e.g. if either end is unable to bind and listen on a specified port). The argument must be "true" or "false". The default is "false".
  • GatewayPorts - Specifies whether remote hosts are allowed to connect to local forwarded ports. By default, azbridge(1) binds local port forwardings to the loopback address. This prevents other remote hosts from connecting to forwarded ports. GatewayPorts can be used to specify that azbridge should bind local port forwardings to the wildcard address, thus allowing remote hosts to connect to forwarded ports. The argument must be "true" or "false".
    The default is "false".
  • LocalForward - Specifies that a (set of) TCP ports on the local machine shall be forwarded via the Azure Relay. Each entry can have four properties, "BindAddress", "Port", "LocalSocket", and "RelayName". See below for details.
  • LogLevel - Gives the verbosity level that is used when logging messages from azbridge(1). The possible values are: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. The default is INFO. DEBUG and DEBUG1 are equivalent. DEBUG2 and DEBUG3 each specify higher levels of verbose output.
  • RemoteForward - Specifies that a TCP port on the remote machine be bound to a name on the Azure Relay. Each entry can have four properties, "RelayName", "Host", "HostPort", and "LocalSocket". See below for details.

LocalForward properties

The following properties are defined for LocalForward. LocalForward is a list and multiple entries are permitted.

  • BindAddress - network address to bind the socket to
  • HostName - remote host name represented by this entry
  • BindPort - TCP port to bind the socket to
  • BindLocalSocket - named UNIX socket to bind to
  • RelayName - name of the Azure Relay name to bind to
  • ConnectionString - Azure Relay connection string to use for this forwarder

Using BindAddress and BindPort is mutually exclusive with use of the BindLocalSocket option. The bind_address argument is optional and when omitted, the default is for the listener to bind to all interfaces.

The RelayName option is always required.

The HostName is property optional and used for documentation. Host names that shall resolve to the -L local forwarder address need to be added to the local hosts file.

The ConnectionString property is optional and overrides the global settings if supplied.

RemoteForward properties

The following properties are defined for RemoteForward. RemoteForward is a list and multiple entries are permitted.

  • RelayName - name of the Azure Relay name to bind to
  • Host - network address to forward to
  • HostPort - TCP port on the host to forward to
  • LocalSocket - named UNIX socket forward to
  • ConnectionString - Azure Relay connection string to use for this forwarder

Using Host and HostPort is mutually exclusive with use of the LocalSocket option. The host argument is optional and when omitted, the default is for the forwarder to connect to the local machine.

The RelayName option is always required.

The ConnectionString property is optional and overrides the global settings if supplied.

Configuration examples

Example 1

This example shows a local configuration that enables local forwarders for three remote computers on different intranets via RDP.

---
GatewayPorts : no
LocalForward:

  # RDP to remote machine abcxyz
  - bind_address: 127.0.10.1
    hostname: abcxyz.intra-de.example.com
    port: 3389
    relay_name: abcxyz-rdp

# SQL to remote machine abcxyz
  - bind_address: 127.0.10.1
    hostname: abcxyz.intra-de.example.com
    port: 1433
    relay_name: abcxyz-sql

  # RDP to remote machine defijk
  - bind_address: 127.0.10.2
    hostname: defijk.intra-us.example.com
    port: 3389
    relay_name: defijk-rdp
  
  # RDP to remote machine ghiuvw
  - bind_address: 127.0.10.3
    hostname: ghiuvw.intra-jp.example.com
    port: 3389
    relay_name: ghiuvw-rdp

Example 2

This example shows a local configuration that enables the remote forwarder for RDP on the computer abcxyz from the prior example.

---
GatewayPorts : no
RemoteForward:

  # RDP to this machine abcxyz
  - relay_name: abcxyz-rdp
    hostport: 3389

Example 3

This example shows a local configuration that enables the remote forwarder for RDP to a computer defijk from the prior example on the remote network, but from a different computer.

---
GatewayPorts : no
RemoteForward:
machine:


  # RDP to remote machine defijk
  - relay_name: defijk-rdp
    host: defijk.intra-us.example.com
    hostport: 3389

Example 4

This example shows a configuration that allows access to a remote SQL server on a local network address of this computer.

---
GatewayPorts : true
LocalForward:

  # SQL to remote machine abcxyz
  - bind_address: 10.10.100.2
    hostname: abcxyz.intra-de.example.com
    port: 1433
    relay_name: abcxyz-sql