Setting Up Padserve and Padclient for Secure Tailnet Communication

Padserve and Padclient are a pair of Go-based applications that provide a secure messaging system over a Tailscale network (Tailnet). Padserve acts as the server, listening for client connections on a Tailscale IP, while Padclient is the client application that users run to send and receive messages. They communicate over TCP within the private Tailnet and use additional cryptographic measures (elliptic curve Diffie-Hellman key exchange with AES or OTP encryption) to secure messages end-to-end. In essence, Padserve coordinates message exchange between connected Padclients, and all communication stays encrypted and confined to your Tailnet for security.

Padserve/Padclient are cross-platform and have been tested on multiple operating systems including Linux, Windows, macOS, and FreeBSD. This guide will focus on setting up Padserve and Padclient on Linux. We’ll walk through installation, configuration, and usage over a Tailscale Tailnet, assuming you have basic networking knowledge and some familiarity with Go. By the end, you will have a working Padserve server and multiple Padclient instances communicating securely over your Tailnet.

Prerequisites

Before installing Padserve and Padclient, make sure you have the following prerequisites in place:

• Go (Golang) 1.23 or later – required to build and run the Padserve/Padclient programs.
• Git – to clone the Padserve and Padclient repositories.
• Tailscale installed and running – all devices (server and clients) must be connected to the same Tailscale network (Tailnet).
• A configured Tailnet (your private Tailscale network) with the Linux machines (or VMs) joined. Ensure you can see each device listed in your Tailscale admin panel or via the tailscale status command.
• Basic firewall openness for Tailnet traffic – the Padserve server listens on TCP port 12345 on the Tailscale interface by default. Typically, Tailnet traffic is peer-to-peer and doesn’t require opening ports externally (What firewall ports should I open to use Tailscale?), but if you run a host firewall (like UFW or iptables), ensure it allows connections from the Tailnet IP range (e.g. 100.64.0.0/10) to port 12345.

Installing Tailscale and Setting Up a Tailnet

If you haven’t set up Tailscale on your Linux systems yet, you’ll need to do that first:

1. Install Tailscale – You can install the Tailscale client via your distribution’s package manager or using the official install script. For a quick installation on Debian/Ubuntu, run: curl -fsSL https://tailscale.com/install.sh | sh This script will download and install Tailscale for your distro (Install Tailscale on Linux · Tailscale Docs). Alternatively, refer to Tailscale’s docs for distribution-specific instructions.
2. Log in to Tailscale – After installation, bring the Tailscale interface up and authenticate the machine to your Tailnet. Run: sudo tailscale up This will prompt you to authenticate (usually by opening a browser and logging into your Tailscale account). Once authenticated, the machine joins your Tailnet (Tailscale quickstart · Tailscale Docs). If you’re setting up a headless server (no browser available), use a pre-authentication key from the Tailscale admin console (e.g., tailscale up --authkey <YOUR_AUTH_KEY>) (Setting up a server on your Tailscale network · Tailscale Docs).
3. Verify Tailnet connectivity – After login, each device gets a unique Tailscale IP (100.x.y.z for IPv4, and an fd7a:… IPv6). You can check this by running tailscale ip -4 (for IPv4) or tailscale status. Make sure your server and clients can see each other’s Tailscale IPs on the Tailnet (try tailscale ping <peer-hostname> or normal ping using the 100.x addresses).

Firewall and Network Considerations

Because Padserve is designed to run only on the Tailscale interface, it will by default bind to the Tailscale-assigned IP and not your public network interface. This means the service is not exposed to the open internet, which is a security advantage. However, local firewall rules could still block traffic on the Tailnet interface:

• If using UFW on Ubuntu (for example), you may need to allow the Tailnet subnet. You can add a rule like: sudo ufw allow from 100.64.0.0/10 to any port 12345 proto tcp to permit Tailnet devices to reach the Padserve port.
• On most systems, Tailscale traffic is automatically allowed or handled, but double-check connectivity if clients cannot reach the server. You might temporarily disable the firewall to test if it’s a firewall issue.
• No port forwarding is needed since Tailscale handles peer-to-peer connectivity (even through NAT). As long as Tailscale is active, devices in the same Tailnet should communicate directly.

Make sure you have Go installed and in your PATH (check with go version). Also ensure git is available to clone repositories. With the environment ready, we can proceed to install the Padserve server.

Installing Padserve (Server)

Padserve will act as the central server for our secure messaging setup. We’ll set it up on a Linux machine that is part of your Tailnet (this could be a cloud VM or a local server, as long as it’s connected to Tailscale). The steps below assume a Unix-like shell on the server machine.

Cloning the Repository

First, download the Padserve source code by cloning its Git repository:

git clone https://github.com/tailsecurity/padserve.git
cd padserve

This will create a directory padserve and put you inside it. The repository contains Go source code for the server.

Building and Running the Server

Padserve is written in Go, so building it is straightforward. In the repository directory, run:

go build

This will compile the Padserve server program. If successful, you should have a binary (executable) named padserve in the directory (or on some systems the binary may be named after the module, but usually it’s padserve given the module name).

Now, before running the server, ensure that the Tailscale daemon is up and running on this machine (tailscale status should show you connected). Padserve will automatically detect the machine’s Tailscale IP when it starts. You can now start the server with appropriate flags:

• To run Padserve binding to the Tailscale IPv4 address: ./padserve -ipv4
• To run Padserve binding to the Tailscale IPv6 address: ./padserve -ipv6
• To enable dual-stack (both IPv4 and IPv6): ./padserve -ipv4 -ipv6

If you omit the flags, the server will default to IPv4-only mode. Padserve listens on port 12345 by default for incoming client connections on the Tailnet interface. When the server starts, it will output its detected Tailscale IP and a message that it’s listening for clients. For example, you might see output indicating it’s listening on 100.x.y.z:12345. This confirms that the server is running and bound to the Tailnet.

Configuring the Server for Tailscale

No special configuration files are needed for Padserve to work with Tailscale – it’s built-in to use the Tailnet. The key points to configure are simply how it binds to the network:

• Tailscale IP selection: Use -ipv4 and/or -ipv6 flags as needed. If your Tailnet primarily uses IPv4 (which is most common), use -ipv4. If you have IPv6 enabled in Tailscale and want to use it, include -ipv6 (you can run both).
• Port number: Padserve uses port 12345 internally; if you needed a different port, you would have to modify the source or use port forwarding on the OS. In most cases, stick with 12345 and ensure that port is free/unblocked.
• Tailnet routing: All clients must be in the same Tailnet as the server. The server will reject or simply not see connection attempts from outside the Tailnet (since its interface is not reachable outside) (GitHub – Tailsecurity/padserve: A server implementation of communications and encryption techniques that runs on the Tailscale network.). So, configuration is mostly about making sure your Tailscale is logged in and devices are authorized.

After running Padserve, leave this terminal/session open to keep the server running (or run it in the background or as a service for long-term use). Next, we will set up Padclient on one or more client machines to connect to this server.

Verifying the Setup

To verify Padserve is working correctly, you can perform a quick check before introducing clients:

• Check server output: The Padserve process should have printed the Tailnet IP and that it’s listening. If it’s not showing an IP or exits immediately, there may be an issue (e.g., Tailscale not active or Go version too low).
• Port check: From another machine on the Tailnet, you can test if the port is accessible. For example, use netcat or telnet: nc -vz 100.x.y.z 12345 (replace with your server’s Tailscale IP). If the connection is established (even though no data is sent yet), it indicates the server is reachable on the network.
• Server commands: Padserve doesn’t accept input from the console (it accepts commands from clients only), but you should be aware it supports commands like LIST, BAN, etc., sent by an operator client. We will see how the client can send these.

Once Padserve is running and listening, we can proceed to install Padclient on client machines to connect to this server.

Installing Padclient (Client)

Now we will set up Padclient on one or more Linux clients. You can also run Padclient on other OS (Windows, macOS, etc., since it’s cross-platform), but here we’ll focus on Linux installation. Each user or device that wants to participate in the secure chat will run a Padclient instance and connect to the Padserve.

Perform these steps on your client machine(s), which should also be connected to the Tailnet (Tailscale should be up and logged in on these machines as well):

Cloning the Repository

Obtain the Padclient code by cloning its GitHub repository:

git clone https://github.com/tailsecurity/padclient.git
cd padclient

This creates a padclient directory with the source code.

Building the Client

Just like the server, Padclient is a Go program. In the padclient directory, run:

go build

This compiles the Padclient binary. You might also run go mod tidy before building to ensure all Go module dependencies are fetched, though running go build should handle downloading required packages automatically.

After a successful build, you should have an executable (for example, padclient) in the directory.

Running the Client

Ensure Tailscale is active on the client machine (tailscale up if not already connected). To start Padclient and connect to the server, you will use the following syntax:

./padclient <YourID> <ServerTailscaleIP>

Here:

• <YourID> is a unique identifier you choose for this client (think of it as your username or client name). For example: Alice or Client1. Each client on the server must have a unique ID; the server will reject duplicate IDs.
• <ServerTailscaleIP> is the Tailscale IP address of the server (the 100.x.y.z or fd7a:… address where Padserve is running).

For instance, if your server’s Tailnet IP is 100.100.50.10 and you want to call this client “Alice”, you would run:

./padclient Alice 100.100.50.10

On first run, Padclient may prompt you or automatically attempt to register with the server. The Padserve server expects a registration, which the Padclient should handle by sending the REGISTER <YourID> command upon connecting. If the registration is successful, you are effectively connected to the Padserve.

Padclient provides a Terminal User Interface (TUI) powered by the Bubble Tea framework. Once running, you should see a text-based interface where you can type commands. If the connection to the server succeeds, the client might display a welcome message or simply be ready for input with no errors.

Connecting the Client to the Server

When Padclient starts with the server’s IP, it will try to connect over the Tailnet. Common things to check if it doesn’t connect:

• Is the Tailscale IP correct and reachable? Double-check you used the right IP (and that the server is still running).
• If using IPv6, you might need to specify the IPv6 address (and ensure you started the server with -ipv6).
• Both server and client must be on the same Tailnet (logged into the same Tailscale network). If you have multiple Tailnets (perhaps using different accounts), ensure the devices appear in the same network list.

If all is well, the client will connect and register. The server’s console should log the new client connection (you might see a message or the client in the output of a LIST command later).

Testing Communication

With one client connected, you can test basic commands. Inside the Padclient TUI, try typing:

• LIST – This should retrieve the list of connected clients from the server (likely showing just your one client ID at this point).
• SERVERHELP – The server will return a list of server-supported commands (like LIST, KICK, etc.), confirming that the client can communicate with the server.

Since meaningful communication requires at least two clients, let’s set up an additional client and then test messaging.

Running Multiple Clients

One of the strengths of Padserve is that it can handle multiple clients in the Tailnet. To simulate a real messaging scenario, you should run at least two Padclient instances (on different machines, or different users). Each client will get a unique ID and connect to the common Padserve server.

Deploying Additional Clients

Repeat the Installing Padclient steps on another Linux machine (or you can even do it on the same machine in a separate terminal, as long as it’s also connected to Tailscale). For example, set up a second client with ID “Bob”:

./padclient Bob 100.100.50.10

Now you should have two clients (e.g., Alice and Bob) connected to the Padserve (100.100.50.10 in this example). Both are in the same Tailnet and the server has registered both IDs. The server requires each client ID to be unique, so ensure you use distinct names.

Configuring Clients to Communicate with the Server

No special configuration is needed for the clients beyond connecting to the correct server IP and using unique IDs. Once connected:

• You can use the LIST command on either client to see both “Alice” and “Bob” listed as active users.
• Each client can send messages either to a specific client or broadcast to all.

For instance, on Alice’s client interface, type:

SEND Bob Hello Bob, this is Alice!

This command will send a private message to the client with ID “Bob”. Over on Bob’s Padclient, you should see the message appear in the interface, indicating it was received. Conversely, Bob can reply with SEND Alice Hi Alice, got your message. and Alice will receive it.

If you use SEND ALL <message> from any client, Padserve will broadcast that message to every connected client. Try having Alice send SEND ALL Hello everyone – both Alice and Bob should see it (Alice sees her own broadcast as well, and Bob sees it as a message from Alice).

This demonstrates that multiple clients can communicate through the Padserve. The encryption is handled behind the scenes: Padserve facilitated an ECDH key exchange with each client when they registered, so all messages are encrypted with either a shared AES key (for broadcasts) or a one-time pad XOR for one-to-one messages. From a user perspective, it behaves like a simple chat room or direct messaging system.

You can also test operator commands. By default, the first client to register might be considered the “operator” (depending on Padserve’s logic). If Alice was started first, try the SERVERINFO or KICK commands from Alice’s client to see if you have operator privileges. Be cautious testing KICK/BAN as it will drop clients; you can always reconnect if needed.

Cloud Deployment References

Running Padserve on a cloud-hosted server is a common scenario for a real deployment (for example, hosting Padserve on a VPS or cloud instance so that clients anywhere can connect via Tailnet). Here are considerations and best practices for cloud deployment:

• Headless Authentication: On a cloud server with no GUI, use a Tailscale auth key to join your Tailnet. Generate an auth key from the Tailscale admin console, then start Tailscale on the server with sudo tailscale up --authkey <key>. This allows the cloud instance to join your Tailnet without manual login (Setting up a server on your Tailscale network · Tailscale Docs).
• Restrict Access with ACLs/Tags: Even though the Tailnet is private, it’s good practice to enforce that only authorized clients can reach the Padserve. In Tailscale’s ACL (Access Control Lists), you could restrict the Padserve’s Tailnet IP (or better, tag the server as “server”) so that only specific users or devices can connect. This adds an extra layer of security in case someone unauthorized gets into your Tailnet.
• Firewall in Cloud: Cloud providers often have their own firewalls or security groups. Generally, you do not need to open any TCP ports to the public internet for Padserve – all traffic goes through the Tailscale interface. Just ensure the cloud instance is allowed to establish outbound UDP connections (for Tailscale’s NAT traversal) and that no internal firewall on the instance blocks Tailnet traffic on port 12345.
• Running as a Service: For production use, you might want Padserve to start on boot and run continuously. Consider creating a systemd service file or using a process supervisor to run padserve -ipv4 -ipv6 on startup. This way, the server is always ready when your cloud instance reboots or updates.
• Monitoring and Logs: In a cloud environment, you might not always have a console attached. Redirect Padserve output to a log file or use a logging tool. Since Padserve currently logs to stdout/stderr, you could run it via systemd (which will capture logs in journalctl) or use something like nohup ./padserve -ipv4 &> padserve.log &.
• Security Best Practices: Keep your Padserve binary up-to-date by pulling new commits from the repository if any security fixes are made. Since the communication is already encrypted end-to-end within the Tailnet, you have a double layer of encryption (WireGuard via Tailscale, and ECDH/AES/OTP in the application). However, continue to enforce strong Tailnet authentication (use MFA on your Tailscale account if possible, enable features like tailnet lock if appropriate) to prevent unauthorized devices from joining. Also, protect the Padserve host machine as you would any server (regular updates, least privilege for accounts, etc.).

By deploying Padserve on a cloud server, you allow geographically distributed clients to connect through Tailscale. The cloud server doesn’t need a public IP for this service; as long as it’s in the Tailnet, clients anywhere (even mobile devices with Tailscale) can securely join the chat.

Troubleshooting and Debugging

Setting up Padserve and Padclient is relatively straightforward, but you might run into some issues. Here are common problems and how to address them:

• Client Cannot Connect to Server: If Padclient fails to connect (e.g., it hangs or exits with an error), verify that:
  • The server’s Tailscale IP is correct and the server is running. You can use tailscale ping <server-ip> from the client machine to ensure the Tailnet connection is working.
  • Both server and client are on the same Tailnet (check tailscale status on both). If not, re-authenticate or double-check you used the correct auth key for the server.
  • No firewall on either side is blocking the traffic. As noted, normally Tailnet traffic should pass, but if you configured restrictive firewall rules, adjust them to allow 100.64.0.0/10 (or your server’s specific Tailnet IP).
  • If you used -ipv6 on the server, ensure you provided an IPv6 address to the client. If the client only has IPv4 connectivity on the Tailnet (common if IPv6 isn’t enabled on your account), run the server with IPv4.
• Duplicate Client ID Rejected: If a client’s terminal shows a message about a duplicate ID or it disconnects immediately, it means another connected client is using the same <YourID>. Choose a different ID for each client (e.g., “User1”, “User2” or actual names). The server will refuse a new client if the ID is already in use.
• Server Immediately Closes: If running ./padserve results in the program exiting or not listening, check that Tailscale is up. Padserve expects a Tailscale interface to be present. Run tailscale up and ensure you have an IP. Then try running Padserve again. Also verify you built the binary with the correct Go version (1.23+). Running go build with an older Go might compile, but you should use the recommended version to avoid any runtime issues.
• Messages Not Received: If one client sends a message but the other doesn’t see it:
  • Check on the sending client if there was an error (Padclient might display an error if the send failed).
  • Use LIST on the server (from an operator client) to ensure the recipient is still listed as connected. If not, the recipient might have been disconnected.
  • Ensure you typed the correct recipient ID (it’s case-sensitive and must match exactly).
  • If broadcasting with SEND ALL, make sure at least one other client is connected; otherwise, it’s just sending to yourself (which might not show up in the UI if the client doesn’t display its own broadcast).
• Server Operator Commands Not Working: Only the client that first registers (or specifically is designated as operator) can issue operator commands like KICK or BAN. If you’re not the operator, SERVERHELP output will not list those commands for you, or attempting them will fail. This is by design. If you need to test these, connect one client first as the admin user, or restart the server and connect with the client you want as operator first.
• Debugging Logs: Padserve and Padclient currently output logs to the console. If you need more insight, run them in a verbose mode if available (check documentation if a -v flag exists; at the time of writing, the README does not mention a verbose flag, so you may need to add print statements in the Go code for deeper debugging). You can also run the server with go run . instead of the binary to get line numbers on panics or errors if something crashes.
• Updating and Rebuilding: If you pull new updates from GitHub and things break, ensure to run go mod tidy and rebuild. Also, when switching between server and client versions, make sure they are compatible. Padclient v0.1.1 is compatible with Padserve 0.1.x. Mismatched versions might cause connection issues if there were protocol changes.

If you encounter other issues, check the Padserve and Padclient GitHub repositories for any opened issues or troubleshooting tips in the README or docs. The Tailscale community is also very helpful if the problem is Tailnet connectivity related. Always isolate whether it’s a networking issue (Tailnet connectivity) or an application issue (Padserve/Padclient bug or misconfiguration).

Conclusion

In this guide, we covered the end-to-end setup of Padserve and Padclient on Linux for secure communication over a Tailscale Tailnet. We started with the prerequisites – installing Go and Tailscale and ensuring all devices are connected to the same Tailnet. We then installed and ran Padserve (server) and confirmed it was listening on the Tailnet IP. Following that, we installed Padclient on multiple clients, connected them to the server using the Tailnet IP, and demonstrated sending encrypted messages between clients. We also discussed how Padserve and Padclient use ECDH key exchange and AES/OTP encryption for secure messaging, adding an extra layer of security on top of Tailscale’s encrypted tunnel.

Key steps to remember:

• Padserve and Padclient require Go and Tailscale; set those up first and verify connectivity in your Tailnet.
• Always run Padserve after Tailscale is up, so it can bind the Tailnet IP (port 12345).
• Use unique client IDs when connecting Padclients to the server, and ensure all clients are in the same Tailnet.
• Test functionality with basic commands (LIST, SEND, etc.) to verify that communication is working.
• For real deployments, consider running Padserve on a stable server (cloud or on-prem) with proper Tailnet access controls and possibly as a background service for reliability.

With Padserve and Padclient running, you now have a private, secure chat system operational within your Tailnet. As next steps, you can explore customizing the code (since it’s open source) to add features or integrate it with other tools. You may also try running Padclient on other platforms (Windows, macOS) to include more participants, as the system is cross-platform. For further information or updates, refer to the Padserve and Padclient GitHub repositories and their documentation. Happy messaging over your secure Tailnet!