Environment Setup

The sidecar is designed to run as a container co-resident to the exchange application it’s serving. However, this is not required; many users of the sidecar appliance run a discrete cluster that exchange servers can reach over the network.

You can begin by running docker run liveramp/idl-mapper:latest -help to see available options.

Runtime Flags

Usage of /gobin/idl-mapperd:
  -certificate string
    	Path to file with client certificate and certificate key to use for authentication
  -dry-run
    	Switch for connecting to Check-in service, if 'true' dummy keys will be used
  -help
    	Print this help text and exit
  -listen string
    	Port or unix socket to listen to (default "unix:///mnt/sock/idl-mapper-socket")

Note that the Docker commands below include the --cap-add IPC_LOCK flag. Enabling this non-default feature is required to protect the sensitive encryption keys used in the sidecar appliance.

The Sidecar application exposes either a socket or a network interface using TCP to process API requests. While accessing the sidecar over a Unix socket has a small performance improvement over the TCP connection when the sidecar is co-resident to the exchange application, we generally recommend using TCP for its relative ease-of-use. In production, the sidecar is run with a -listen flag, that accepts addresses of the form unix:///path/to/socket or tcp://:port-number.

TCP Network Interface Example

docker run --cap-add IPC_LOCK -p 127.0.0.1:3000:3000 liveramp/idl-mapper:latest -listen tcp://:3000 -certificate "/path/to/cert"

Note that the unix socket path should always fall under the /mnt/sock directory on the container, which can be shared with other containers or mounted externally via a docker volume mount at runtime.

Unix Socket Example

docker run --cap-add IPC_LOCK -v /path/to/host/socket/dir:/mnt/sock liveramp/idl-mapper:latest -listen unix:///mnt/sock/idl-mapper-socket -certificate "/path/to/cert"

In the case above, /path/to/host/socket/dir/idl-mapper-socket will appear on the host.

📘

A note on socket sharing

Docker currently doesn’t support sharing sockets over a hypervisor. If you’re testing the sidecar on a non-Linux machine and try to mount the sidecar’s socket to your host, the socket itself won’t appear on the host without an error. For the time being, this testing needs to be done either on a VM or in a native Linux environment.

The client certificate and client key will be provided by LiveRamp. Note that these will also have to be mounted in the container at /mnt/secrets via the same method as described above. Running in development mode (by passing the dry-run argument) will skip certificate validation, but will still check for the existence of the flag as a runtime argument.

dev image example

docker run --cap-add IPC_LOCK -p 127.0.0.1:3000:3000 liveramp/idl-mapper:latest -listen tcp://:3000 -certificate " " -dry-run true

Security Measures

The application runs completely memory-locked within the container, in order to prevent any sensitive keys from being written to disk, so the application must be given the permissions and resources to effectively lock enough memory. The application shouldn’t need more than 10MB.

The application will not run unless the container has its core file size hard limit set to 0, in order to prevent any sensitive keys being written out in core dumps. If the container is run with this value set to anything above 0, a warning message will be printed to STDOUT and the value will be overwritten to 0.

❗️

Important

Attempting to modify directories other than /mnt/sock and /mnt/secrets on the sidecar can result in triggering tamper-prevention mechanisms, which could result in an account-wide disruption of service.

Network Traffic and Telemetry

The sidecar container needs to be able to communicate with LiveRamp’s services at sidecar.liveramp.com to periodically (every one and five minutes) check in, obtain and renew keys and to send telemetry and crash reports. In most cases, this requires no special Docker setup, however it may be impacted if you’re using a special networking mode.

📘

Sidecar IP Addresses

The sidecar will connect to sidecar.liveramp.com. If you need to whitelist specific IP addresses, you may use 35.193.49.161 and 35.188.138.165.

See API endpoints for information on what aggregated telemetry is collected.