Skip to main content
This page covers information about listener configurations

​
Introduction

Listeners are instantiated on the Merlin Server and are how Merlin Agents communicate with the server. Listeners are configured through the Merlin CLI. Listeners contain the configuration that the Merlin Server uses to understand Merlin Agent traffic. Some Listeners have an associated associated server, like an HTTP server, not to be confused with the Merlin Server. Peer-to-peer Listeners do not have a server because traffic is passed to them through delegate messages, they don’t actually bind to a network interface. Available Listener types are:
  • HTTP - Uses the HTTP/1.1 protocol to communicate with Merlin Agents without TLS
  • HTTPS - Uses the HTTP/1.1 protocol to communicate with Merlin Agents with TLS
  • H2C - Uses the HTTP/2 clear-text protocol to communicate with Merlin Agents without TLS
  • HTTP2 - Uses the HTTP/2 protocol to communicate with Merlin Agents with TLS
  • HTTP3 - Uses the UDP-based HTTP/3 protocol (HTTP/2 over QUIC) to communicate with Merlin Agents with TLS
  • SMB - Processes messages for SMB-based peer-to-peer Agents but does not listen for traffic itself, just handling
  • TCP - Processes messages for TCP-based peer-to-peer Agents but does not listen for traffic itself, just handling
  • UDP - Processes messages for UDP-based peer-to-peer Agents but does not listen for traffic itself, just handling

​
Core Configuration Options

The following configuration options are standard across all Listener types:

​
Authenticator

The Authenticator configuration option is used to set what method of authentication is used by the Merlin Agent to authenticate to the server. The following options are available:
  • OPAQUE - This is the default option and uses the OPAQUE Asymmetric Password Authenticated Key Exchange (PAKE)
  • None - This option disables authentication and allows any Merlin Agent to connect to the Listener

​
Description

The Description configuration option is used to set a description for the Listener. Mainly used by operators to describe the purpose of the Listener.

​
ID

The ID is a UUID for the instantiated listener tracked on the Merlin Server. If this value is not set, a random one will be generated when the Listener is created. The ID field can be set to a specific UUID before it is created. This is useful when the Server is restarted and the Listener needs to be recreated. It is also useful when a peer-to-peer Agent was configured to communicat with a specific Listener ID does not exist.

​
Name

The Name configuration option is used to set a name for the Listener. Mainly used by operators to identify the listener in tables displayed in the Merlin CLI.

​
Protocol

The Protocol configuration option is used to set what protocol the Listener will use to communicate with the Merlin Agent.
Because peer-to-peer listeners do not have an associated server, there are not separate types for bind and reverse
The following options are available:
  • HTTP - Uses the HTTP/1.1 protocol to communicate with Merlin Agents without TLS
  • HTTPS - Uses the HTTP/1.1 protocol to communicate with Merlin Agents with TLS
  • H2C - Uses the HTTP/2 clear-text protocol to communicate with Merlin Agents without TLS
  • HTTP2 - Uses the HTTP/2 protocol to communicate with Merlin Agents with TLS
  • HTTP3 - Uses the UDP-based HTTP/3 protocol (HTTP/2 over QUIC) to communicate with Merlin Agents with TLS
  • SMB - Processes messages for SMB-based peer-to-peer Agents but does not listen for traffic itself, just handling
  • TCP - Processes messages for TCP-based peer-to-peer Agents but does not listen for traffic itself, just handling
  • UDP - Processes messages for UDP-based peer-to-peer Agents but does not listen for traffic itself, just handling

​
PSK

The default PSK is merlin and should not be used
The PSK configuration option is used to set the pre-shared key that is used to encrypt traffic between the Merlin Agent and the Listener.

​
Transforms

The Transforms option is used to specify the ordered list of transforms that will be used to construct/deconstruct a message. The default value is jwe,gob-base. The transforms are applied in the order they are specified.
The gob-base transform must be the last transform in the list to unmarshall into a Go structure
Available transforms consist of encoders and encrypters:
  • aes - AES encrypt/decrypt the data
  • base64-byte - Encode/decode the data to/from base64 as bytes using the EncodeLen() function
  • base64-string - Encode/decode the data to/from base64 as a string using the EncodeToString() function
  • hex-byte - Encode/decode the data to/from hex as bytes using the EncodeLen function
  • hex-string - Encode/decode the data to/from hex as a string using the EncodeToString function
  • gob-base - Gob encode/decode the message in to a Merlin Base message structure
  • gob-string - Gob encode/decode the message in to a string
  • jwe - Encode/decode the data into a JSON Web Encryption (RFC 7516) structure
  • rc4 - Encode/decode the data using the RC4 stream cipher
  • xor - Encode/decode the data using the XOR cipher
The JWE transform uses the following configuration:
  • Encrypter: A256GCM
  • Algorithm: PBES2_HS512_A256KW
  • PBES2Count: 3000

​
HTTP Configuration Options

The following configuration options are specific to HTTP-based Listeners:

​
HTTP Interface

The Interface configuration option is used to set the network interface that the Listener will bind to. The default is the loopback adapter at 127.0.0.1.
Use 0.0.0.0 as a shortcut for all interfaces

​
JWTKey

The JWTKey configuration option is used to set the key that is used to sign & encrypt the JWTs that Merlin Agents use to authenticate to the HTTP server. The key is represented as a base64 encoded string. This is useful when the Merlin Server has restarted but existing Merlin Agents are still using the old key. However, Merlin Agent’s can recover if a new JWTKey is used so long as the PSK matches. If a JWTKey is excluded, or set to an empty value, then JWTs will not be used by the HTTP server to authenticate Merlin Agents. This is useful to disable using JWTs all together.

​
JWTLeeway

The JWTLeeway configuration option is used to set the leeway for JWTs that are used to authenticate Merlin Agents. The Leeway is the amount of time difference, or skew, that is allowed between the Merlin Agent and the Merlin Server. This is very common for systems that are not synchronized with NTP such as virtual machines. If the time between the Server and the Agent is greater than the leeway, the JWT will be rejected and the Agent message will be rejected.

​
HTTP Port

The Port configuration option is used to set the port that the Listener will bind to.

​
URLS

The URLS configuration option is used to set the URLs that the HTTP server can receive Merlin Agent traffic on. Provide a comma separated list of URLs as a string. The HTTP server will reject Agent messages that are received on URLs not in the list.

​
X509Cert

The X509Cert configuration option is used to set the X509 certificate that the HTTP server will use server TLS connections.
If a valid certificate path is not provided, the server will generate a self-signed certificate

​
X509Key

The X509Key configuration option is used to set the X509 key that the HTTP server will use to encrypt traffic.

​
SMB Configuration Options

​
Pipe

The Pipe configuration option is used to set the named pipe that peer-to-peer SMB communications will occur on. Only include the name of the pipe. Do not include the UNC path or the interface. The SMB listener does not have an associated server, so the listener itself does not create or listen on the named pipe. It is just used to identify the configuration the Agent will use.

​
TCP Configuration Options

​
TCP Interface

The Interface configuration option is used to set the network interface that peer-to-peer Agents will bind or connect to. The TCP listener does not have an associated server, so the listener itself does not create or listen on the named pipe. It is just used to identify the configuration the Agent will use.

​
TCP Port

The Port configuration option is used to set the port that peer-to-peer Agents will bind or connect to. The TCP listener does not have an associated server, so the listener itself does not create or listen on the named pipe. It is just used to identify the configuration the Agent will use.

​
UDP Configuration Options

​
UDP Interface

The Interface configuration option is used to set the network interface that peer-to-peer Agents will bind or connect to. The UDP listener does not have an associated server, so the listener itself does not create or listen on the named pipe. It is just used to identify the configuration the Agent will use.

​
UDP Port

The Port configuration option is used to set the port that peer-to-peer Agents will bind or connect to. The UDP listener does not have an associated server, so the listener itself does not create or listen on the named pipe. It is just used to identify the configuration the Agent will use.