Automatic laptop access maintenance

Status: Pilot; native startup acceptance pending | Last reviewed: 2026-09-23

Use this optional setup to start the TrueServe tunnel after a reboot, recover when the core VPN becomes available, and follow Dev/QA IP address changes. The city must publish route discovery before a laptop enables this mode. Keep the normal core VPC VPN installed and sign in when it requests MFA.

What runs automatically

Where	Interval	Work
City host	About 60 seconds	Query the trusted city DNS resolver, update the relay's forwarding destinations and scoped DNS, and publish destination discovery inside the tunnel
Mac or Windows laptop	30 seconds while awake	Start/recover its TrueServe tunnel and reconcile the selected environment's destination routes
Mac or Windows laptop	30 minutes while connected	Check Dev/QA Studio HTTPS and record the result

The laptop job starts at system startup. When it wakes or its connection recovers, it retries. Checks use one both profile for simultaneous Dev and QA. The 30-minute HTTPS check is separate from route discovery: an IP change should not leave the laptop waiting half an hour.

There can still be a short interruption during DNS rotation, normally up to the city refresh interval plus the laptop check interval. This is eventual recovery, not a promise of uninterrupted calls. Browser audio needs a real call test; HTTPS, routes and DNS do not prove authenticated TURN allocation.

The helpers preserve the core VPN and default route. They change only the TrueServe interface, selected destinations and exact-name DNS settings. An explicit route owned by another interface is reported as a conflict. The Mac helper may move an OS-generated cached host route for a discovered destination; it does not take over another VPN's explicit static route.

Prepare the city

Run these commands on the EC2 host, through SSM or its normal host shell. Use a root-owned committed tools release, Python 3, Docker, systemd and dig. The existing relay must already work. Install the host's dnsutils package if dig is missing.

First inspect the names and destinations being enrolled in the existing private relay state. This job refreshes only those catalog names, never arbitrary laptop-supplied names. Its default upstream is the AWS VPC resolver at 169.254.169.253; use --resolver IP if this city requires a different trusted resolver. Direct DNS queries avoid stale /etc/hosts entries.

For Windows OpenVPN:

sudo python3 /opt/trueserve-openvpn/current/scripts/studio-access/maintain.py \
  install --transport openvpn
sudo trueserve-openvpn export jyoti-windows

For Mac WireGuard:

sudo python3 /opt/trueserve-access/current/scripts/studio-access/maintain.py \
  install --transport wireguard
sudo trueserve-access export DEVICE_NAME

Enable each transport separately. Installation first runs a complete DNS refresh, checks the managed container identity, and publishes discovery. It then enables a systemd timer. No application checkout, application container, VPN identity, certificate or host firewall rule is replaced.

Deliver a fresh private device bundle to the laptop owner. Older helpers and manually imported profiles do not gain automatic behavior merely because the city timer is enabled. Existing manual clients still use fixed routes and may need a replacement profile after an IP change.

Inspect or disable the host job:

sudo python3 /opt/trueserve-openvpn/current/scripts/studio-access/maintain.py \
  status --transport openvpn
sudo journalctl -u trueserve-maintain-openvpn.service -n 30
sudo python3 /opt/trueserve-openvpn/current/scripts/studio-access/maintain.py \
  disable --transport openvpn

Use wireguard and the WireGuard tools path for the other transport. Disabling the timer retains the last working DNS/routes and the relay itself. Timers retry failures; the status file and systemd journal need operator monitoring if a city remains unreachable.

Mac one-time setup

Use an updated city WireGuard bundle containing auto-mac.sh and the both, dev and qa folders. Homebrew wireguard-tools must be installed. The older standalone StudioTest.conf package is not this bundle. For the original Vanguard connection, use the replacement StudioTest-Automatic-Mac bundle after its host has been adopted into maintenance. It keeps the same endpoint and device identity.

Before using that replacement, run these in the old StudioTest-mac folder:

sudo bash studio-dns.sh disable
sudo env PATH="$PATH" wg-quick down ./StudioTest.conf

The first command removes the old DNS overrides. The second disconnects the manual TrueServe tunnel, so the automatic helper can own it. Keep the core VPN connected. If wg-quick reports that the interface is already absent, continue with installation from the new bundle.

1. Connect the core VPC VPN. This gives the laptop a route to the city.
2. Stop the manual TrueServe connection. For the city CLI helper, run sudo bash mac.sh down; for its GUI mode, run sudo bash mac.sh dns-off and deactivate that TrueServe profile in WireGuard.
3. From the extracted new bundle folder, install the startup job:

bash sudo bash auto-mac.sh install both

This copies the device configuration into a protected system folder and installs a LaunchDaemon. It can run after reboot without another sudo prompt. Keep the old manual TrueServe profile disconnected.

1. Wait about a minute, then inspect the result:

bash sudo bash "/Library/Application Support/TrueServeAccess/auto-mac.sh" status

The status includes the last route/DNS check, interface and HTTPS results. A “Waiting for the core VPN” result means the normal company VPN must connect first.

1. Open Dev and QA Studio and test a voice call in each. Then test a reboot and a sleep/wake cycle with the core VPN disconnected and reconnected.

To stop automatic access:

sudo bash "/Library/Application Support/TrueServeAccess/auto-mac.sh" uninstall

This unloads the job, disconnects only its TrueServe tunnel and removes its managed DNS settings. A private configuration backup remains beside the installation directory. To switch environments, uninstall, then install dev, qa or both from the bundle. Do not run the manual helper alongside the automatic one.

Windows one-time setup

Use an updated OpenVPN bundle containing auto-windows.ps1, auto-both.json and the corresponding .ovpn files. This mode uses OpenVPN Community 2.7+ and its DCO driver. Installation may require company IT. WireGuard and its windows.ps1 helper are not used for this mode.

1. Keep the core VPC VPN connected.
2. In OpenVPN GUI, disconnect the old TrueServe profile. This prevents two connections from using the same device certificate.
3. Open 64-bit Windows PowerShell as Administrator in the new bundle folder and run:

powershell .\auto-windows.ps1 install both

This copies the profile into a folder accessible only to Administrators and SYSTEM. It registers the TrueServeAccess-Maintain startup task and starts it immediately. The task owns its OpenVPN process; the GUI profile stays disconnected.

1. Wait about a minute, then run in the same elevated PowerShell:

powershell & "$env:ProgramData\TrueServeAccess-Auto\auto-windows.ps1" status

connected means tunnel route discovery completed. Check the separate health results for application reachability. retrying includes a reason; connect the core VPN if it is offline.

1. Open both Studio environments and test audio. Test reboot and sleep/wake recovery before treating this pilot as an unattended company rollout.

To stop the automatic connection:

& "$env:ProgramData\TrueServeAccess-Auto\auto-windows.ps1" uninstall

This removes the task and signals its own OpenVPN process to disconnect cleanly. It also removes its discovered routes, checking adapter ownership and gateway first. Private settings remain in a dated backup folder. Other OpenVPN profiles and services are not stopped. To switch environments, uninstall and run install dev, install qa or install both from the bundle.

How address changes stay bounded

The original Vanguard relay can be explicitly adopted without changing its container, endpoint or keys. Its root-owned maintenance state lives in /var/lib/studio-test-access; the maintenance job checks the recorded container ID, server public key, port binding and original startup command. After adoption, the host command is:

sudo python3 /opt/studio-test-access/current/scripts/studio-access/maintain.py \
  install --transport wireguard --legacy-studio-test

Use status or disable with the same flags to inspect or stop that timer. The original gateway's destinations file remains a list of bare IPv4 addresses, because its boot script adds /32 itself. Replacing the container requires deliberate re-adoption; a matching container name alone is insufficient.

Discovery is a DNS A-record set at routes-both.access.trueserve.invalid (or routes-dev / routes-qa), queried directly against the tunnel's DNS address. It is available only through the authenticated tunnel, not a public download endpoint. It carries IPv4 addresses, not executable instructions or credentials.

The host installs forwarding rules before publishing new answers. An old address remains in discovery for ten minutes for cached connections. It expires afterward unless another selected hostname still uses it or it is also an explicitly configured extra destination. Reviewed extra destinations remain until the operator removes them. Failed DNS lookups retain the affected name's last known addresses.

Discovery is capped at 128 routes and excludes recursive endpoint/tunnel addresses, metadata, loopback and multicast destinations. Extra media CIDRs are still explicitly reviewed static routes. A newly introduced hostname or a media address absent from the enrolled DNS catalog needs operator review; this is not an unrestricted full-tunnel VPN.

Credentials and remaining limits

Company VPN MFA and application SSO remain interactive. OpenVPN device certificates still expire after 30 days. The Windows health report includes their expiry and sets renewalNeeded during the final seven days. The helper does not renew certificates or Grafana tokens. Arrange renewal and deliver a new private device bundle before expiry.

Status is written locally; these jobs do not send email or chat alerts. Administrators can inspect the protected status files and systemd journal. An application outage is recorded without restarting city applications or resetting the core VPN.

Linux tests exercise live tunnel DNS rotation, route discovery and forwarding. Mocked PowerShell tests exercise route ownership and recovery; Bash syntax and the LaunchDaemon plist are checked. Native Windows/macOS startup, driver, device-policy and sleep/wake acceptance remain required.

See also

• Mac laptop setup
• Windows OpenVPN setup
• City OpenVPN relay