Introduction
In this article, we will go over how to configure a HCP Self-Managed Boundary Worker under the systemd
init system on modern Linux distributions.
Prerequisites
- Access to an HCP Boundary instance. This example was performed on Ubuntu/Linux.
- An instance on a public or private network to be used as a worker that meets the Network Requirements defined here.
-
Requires the Boundary Enterprise binary for Linux, MacOS, Windows, BSD and Solaris (more info here). This process will create:
- A worker config file: "/etc/boundary.d/worker.hcl"
- A systemd file: "/usr/lib/systemd/system/boundary.service"
Note: For self-managed worker registration with HCP Boundary, the binary version should match the version of the HCP control plane. Check the version of the control plane in the HCP Boundary portal, and if the version installed from above doesn't match, download the appropriate version and overwrite the existing worker binary in "/usr/bin/boundary-worker".
- Create a directory to be used as the "auth_storage_path". The worker will write a credentials file to this directory. In this example, we will be using "/home/boundary/worker1".
- Add the boundary system user and group to the "auth_storage_path" and worker binary to ensure we have no-login user capable of owning and running Boundary.
$ sudo chown boundary:boundary /home/boundary && sudo chown boundary:boundary /home/boundary/worker1
$ sudo chown boundary:boundary /usr/bin/boundary-worker
Use Case
HCP Boundary allows organizations to register their own PKI Workers. Self-managed workers can be deployed in private networks while still communicating with an upstream HCP Boundary cluster.
Procedure
- Open the worker config file at "/etc/boundary.d/worker.hcl" with a text editor, such as vi, and replace the template with your config. Reference this Guide for options & requirements.
Note: If deploying in a private network, use the private ip as the value of "public_addr".
disable_mlock = true
hcp_boundary_cluster_id = "<cluster_id>"
listener "tcp" {
address = "0.0.0.0:9202"
purpose = "proxy"
}
worker {
public_addr = "<public or private ip>"
auth_storage_path = "</home/boundary/worker1>"
tags {
type = ["worker", "dev"]
}
}
Add the boundary system user and group to the worker.hcl file.
$ sudo chown boundary:boundary /etc/boundary.d/worker.hcl
- Open the systemd unit file in "/usr/lib/systemd/system/boundary.service" with a text editor, such as vi, and update the "ExecStart=" parameter to point to the worker.hcl config file and boundary-worker binary.
Comment out "ProtectHome=read-only", as this will prevent the worker from writing it's credentials to the auth_storage_path on startup.
[Unit]
Description="HashiCorp Boundary - Identity-based access management for dynamic infrastructure"
Documentation=https://www.boundaryproject.io/docs
#StartLimitIntervalSec=10
#StartLimitBurst=0
[Service]
EnvironmentFile=-/etc/boundary.d/boundary.env
User=boundary
Group=boundary
ProtectSystem=full
#ProtectHome=read-only
ExecStart=/usr/bin/boundary-worker server -config=/etc/boundary.d/worker.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target
- Start the worker.
$ sudo systemctl start boundary
- Verify the worker is running and make note of the Worker Auth Registration Request ID, which will be used to register the worker with HCP. Reference this Guide for registration instructions.
$ sudo systemctl status boundary
boundary.service - "HashiCorp Boundary - Identity-based access management for dynamic infrastructure"
Loaded: loaded (/lib/systemd/system/boundary.service; disabled; vendor preset: enabled)
boundary.service - "HashiCorp Boundary - Identity-based access management for dynamic infrastructure"
Loaded: loaded (/lib/systemd/system/boundary.service; disabled; vendor preset: enabled)
Active: active (running) since Wed 2022-12-21 22:39:38 UTC; 4min 19s ago
Docs: https://www.boundaryproject.io/docs
Main PID: 3390 (boundary-worker)
Tasks: 6 (limit: 1143)
Memory: 17.1M
CPU: 2.471s
CGroup: /system.slice/boundary.service
└─3390 /usr/bin/boundary-worker server -config=/etc/boundary.d/worker.hcl
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Log Level: info
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Mlock: supported: true, enabled: false
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Version: Boundary v0.11.0+hcp
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Version Sha: 319ea70c5f88c66482abc2d724acd172037ebf63
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Worker Auth Current Key Id: quote-shortcut-algebra-skype-widen-reward-radiated-tribune
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Worker Auth Registration Request: pdZ5SAAebKa9DmnokkNu5EuBMzPos7sRz7HzjsgbwhwZncFWBfEUuG9zGKjz4haerRetUAEYYnGdobn14oZAoSCGuece2ESCTCYmvznFu23zYJvtNBCAN7HCwksR7ajf4ayvvRgq7rVwi7gxa7K524rsAaZrs8vWaqHSCJaTnKeDynJgiq2iNUP8oi2TLthNsPQ6NjC5FGYxWnPKthmHDVfPsgFa1QoXbbWgtVpwoiUPRZvsNcx9M8YHJREPp2gH9tQzochyA1WPqGjA7Y48X4SMY4XvaHSfJ8CXeJ2
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Worker Auth Storage Path: /home/boundary/worker1
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: Worker Public Proxy Addr: 10.0.140.232:9202
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: ==> Boundary server started! Log data will stream in below:
Dec 21 22:39:38 ip-10-0-140-232 boundary-worker[3390]: {"id":"p4XGv2KmY1","source":"https://hashicorp.com/boundary/ip-10-0-140-232/worker","specversion":"1.0","type":"system","data":{"version":"v0.1","op":"worker.(Worker).StartControllerConnections","data":{"msg":"Setting HCP Boundary cluster address 13342cb1-805e-462a-8b3e-ae6ht535ec9.proxy.boundary.hashicorp.cloud:9202 as upstream address"}},"datacontentype":"application/cloudevents","time":"2022-12-21T22:39:38.252510564Z"}
Note: A file called "auth_request_token" is created in the "auth_storage_path" when you start the service. This also contains the Worker Auth Registration Request ID to use for registration.
- Finally, configure the boundary.service to auto start at boot up.
$ sudo systemctl enable boundary
Additional Information
For additional questions or support, please open a Support ticket.