How to Create a Service

This guide shows you how to create a service that routes traffic between two Arctic agents.

Before You Start

Ensure you have:

• At least two connected peers in your cluster
• The target peer ID (the peer that will receive traffic)
• Appropriate permissions (services.write scope)

Basic Service Creation

1. Find the Target Peer ID

List peers to find the ID of the destination peer:

arctic peers list

2. Create the Service

Create a basic TCP service:

arctic services create --target-peer TARGET_PEER_ID

This creates a service from the local peer to the target peer using TCP transport.

Advanced Options

With MACVLAN Interface

Create a service with a dedicated network interface for traffic isolation:

arctic services create \
  --target-peer TARGET_PEER_ID \
  --requires-interface

With Specific IP Addresses

Request specific IP addresses for the MACVLAN interface:

arctic services create \
  --target-peer TARGET_PEER_ID \
  --requires-interface \
  --desired-ipv4 192.168.100.10/24 \
  --desired-ipv6 fd00::10/64

With Bandwidth Limit

Apply QoS bandwidth limiting:

arctic services create \
  --target-peer TARGET_PEER_ID \
  --bandwidth-limit 1000

The bandwidth limit is in Mbps. Set to 0 for unlimited.

With Fully Transparent Mode

Enable Transparent Mode to preserve the original source IP address at the destination:

arctic services create \
  --target-peer TARGET_PEER_ID \
  --fully-transparent \
  --requires-interface

This is useful when the destination needs to see the real client IP for logging, access control, or rate limiting. See Transparent Mode for details.

Note: Transparent Mode requires --requires-interface and only works with TCP traffic.

With KCP Transport

Use KCP instead of TCP for the underlying transport:

arctic services create \
  --target-peer TARGET_PEER_ID \
  --transport kcp

KCP provides better performance over high-latency or lossy networks.

From a Specific Source Peer

By default, the source peer is the local agent. To create a service from a different peer:

arctic services create \
  --source-peer SOURCE_PEER_ID \
  --target-peer TARGET_PEER_ID

Complete Example

Create a fully-configured service:

arctic services create \
  --target-peer 01HXYZDEF789... \
  --transport tcp \
  --requires-interface \
  --desired-ipv4 192.168.100.10/24 \
  --bandwidth-limit 1000

After Creating a Service

A service alone does not route traffic. You must add routes to specify which traffic should use the service.

See Configure Routes for instructions on adding routing rules.

Troubleshooting

Target Peer Not Found

If the target peer ID is not found:

1. Verify the peer exists: arctic peers list
2. Ensure the peer has completed handshake (not just discovered)

Service Limit Exceeded

If you receive a service limit error:

1. Check your license: arctic license show
2. Delete unused services or upgrade your license

Interface Creation Failed

If the MACVLAN interface fails to create:

1. Check agent logs: journalctl -u arctic-agent | grep netmgr
2. Verify the host has a suitable parent interface
3. Ensure the agent has root privileges

Related

• Transparent Mode - Source IP preservation details
• Configure Routes
• Set Bandwidth Limits
• Delete a Service
• services CLI Reference