tailscale-rs

https://tailscale.com

tailscale-rs is a work-in-progress Tailscale library written in Rust, with language bindings to C, Elixir, and Python.

Note

This software is under active development. See Caveats for more details.

Getting Started

The following instructions are for Rust! For other languages, see the language-specific README:

• C
• Elixir
• Python

Add this dependency line to your Cargo.toml:

[dependencies]
tailscale = { version = "0.5" }

Examples of using the tailscale crate can be found in examples/.

For instructions on how to run tests, lints, etc., see CONTRIBUTING.md. For the high-level architecture and repository layout, see ARCHITECTURE.md.

Code sample

A simple UDP client that periodically sends messages to a tailnet peer at 100.64.0.1:5678:

use std::{
    time::Duration,
    net::Ipv4Addr,
    error::Error,
};
use tailscale::{Config, Device};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Open a new connection to tailscale
    let dev = Device::new(
        &Config::default_with_key_file("tsrs_keys.json").await?,
        Some("YOUR_AUTH_KEY_HERE".to_owned()),
    ).await?;

    // Bind a UDP socket on our tailnet IP, port 1234
    let sock = dev.udp_bind((dev.ipv4().await?, 1234).into()).await?;

    // Send a packet containing "ping" to 100.64.0.1:5678 once per second
    loop {
        sock.send_to((Ipv4Addr::new(100, 64, 0, 1), 5678).into(), b"ping").await?;
        tokio::time::sleep(Duration::from_secs(1)).await;
    }
}

Caveats

This software is still a work-in-progress! We are providing it in the open at this stage out of a belief in open-source and to see where the community runs with it, but please be aware of a few important considerations:

• There are no compatibility guarantees at the moment. We may break dependent code in order to get things right, although we will try to avoid doing so gratuitously.
• Direct connections via NAT traversal is a work in progress. Communication may fall back to DERP relaying in more cases, with a corresponding hit to latency and throughput.
• Core networking functionality is implemented. Many other features are still either in progress or not implemented yet. See Status for details.

We encourage you to experiment with this library and build things with it, as long as you're okay with these caveats.

Versioning, Releases, and Compatibility

We follow semver and aim to make a point release roughly monthly. Since we are pre-1.0, we make no strong backwards-compatibility guarantees.

MSRV and Edition

The current MSRV is 1.97. The current edition is Rust 2024.

tailscale-rs has a rolling MSRV (Minimum Supported Rust Version) policy to support the current and previous Rust compiler versions, and the latest edition of Rust.

We may periodically lag the MSRV behind this latest version/edition in rare cases for our dependencies to catch up and for us to perform any necessary fixes.

Platform Support

We support the following platforms and architectures:

• Linux (x86_64/ARM64)
• macOS (ARM64)
• Windows (x86_64)

Status

tailscale-rs is a work-in-progress. We're still rapidly iterating, fixing bugs, and adding new features. We aim to keep this section up-to-date, but our issue tracker is the best way to see the latest updates.

Implemented

These are features that we currently implement:

• Basics
  • Create TCP and UDP sockets on the tailnet
  • Communicate with peers via public DERP relays
  • Communicate with the Tailscale Go client, tsnet, and libtailscale
• Language support
  • Rust API
  • C, Elixir, and Python bindings

Coming Soon

These are features or efforts we have in the pipeline and are actively working towards, but provide no guarantees on timeline or completion:

• Direct connections (NAT traversal, STUN, and Disco)
• Peer lookups (addressing peers by hostname)

Unsupported

This is an incomplete list of features in the Tailscale Go client, tsnet, and/or libtailscale that we currently do not support. We'd like to add all of these eventually! If there's something on this list you'd like to see supported, or something not on this list you're not sure about, please open an issue!

Unsupported features

• Networking
  • Peer relays
  • Exit Nodes (either being one, or using one)
  • MagicDNS
  • Private DERP relays
  • Split DNS
  • Subnet Routers (either being one, or using one)
• Platforms
  • AIX
  • Android
  • BSDs
  • iOS
  • Plan9
  • QNAP
  • Synology DSM
• Observability
  • Client Metrics
  • Endpoint Collection
  • Device Posture Collection
  • Log Streaming
  • Network Flow Logs
• Other Features
  • Application Capabilities
  • Automatic Key Rotation
  • HTTPS Certificates
  • Kubernetes
  • Mullvad VPN
  • Node Sharing
  • Taildrive
  • Taildrop
  • Tailnet Lock
  • Tailscale Funnel
  • Tailscale Serve
  • Tailscale SSH
  • Tailscale Services
  • Webhooks
• Any other features not listed in "Implemented" or "Coming Soon"

Legal

WireGuard is a registered trademark of Jason A. Donenfeld.