Ockam Command Manual

ockam relay

ockam relay <COMMAND>

Communication topologies often encounter situations where the machine providing a service cannot or will not open a listening port or expose a bridge node to other networks. This is a common security best practice in enterprise environments, home networks, OT networks, and VPCs across clouds. Application developers may not have control over these choices from the infrastructure/operations layer. In such cases, relays are useful.

Relays make it possible to establish end-to-end protocols with services operating in a remote private networks, without requiring a remote service to expose listening ports to an outside hostile network like the Internet.

Subcommands

• create
• list
• show
• delete

Examples

# Create two nodes blue and green
$ ockam node create blue
$ ockam node create green

# Create a relay to node blue at node green
$ ockam relay create blue --at /node/green --to /node/blue

# Send a message to the uppercase service on blue via its relay on green
$ ockam message send hello --to /node/green/service/forward_to_blue/service/uppercase

This can be very useful in establishing communication between applications that cannot otherwise reach each other over the network.

For instance, we can use relays to create an end-to-end secure channel between two nodes that are behind private NATs:

# Create another node called yellow
$ ockam node create yellow

# Create an end-to-end secure channel between yellow and blue.
# This secure channel is created through blue's relay at green, and we can
# send end-to-end encrypted messages through it.
$ ockam secure-channel create --from /node/yellow --to /node/green/service/forward_to_blue/service/api \\
    | ockam message send hello --from /node/yellow --to -/service/uppercase

In this topology green acts as an encrypted relay between yellow and blue. Yellow and blue can be running in completely separate private networks. Green needs to be reachable from both yellow and blue and only sees encrypted traffic.

You can find more details within the documentation:

• https://docs.ockam.io/reference/command/advanced-routing#relays