### Start Lightway Client

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Builds and starts the Lightway client within a specified network namespace. It requires root privileges and uses a configuration file.

```bash
cargo build --bin lightway-client && sudo -E ip netns exec lightway-client ./target/debug/lightway-client --config-file './tests/client/client_config.yaml'
```

--------------------------------

### Start Lightway Server

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Builds and starts the Lightway server within a specified network namespace. It requires root privileges and uses a configuration file.

```bash
cargo build --bin lightway-server && sudo -E ip netns exec lightway-server ./target/debug/lightway-server --config-file './tests/server/server_config.yaml'
```

--------------------------------

### Lightway Server Configuration

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Command to start the Lightway server with a specified configuration file.

```bash
lightway-server --config-file './tests/server/server_config.yaml'
```

--------------------------------

### Install and Run cargo-fuzz

Source: https://github.com/expressvpn/lightway/blob/main/lightway-core/README.md

Installs cargo-fuzz and provides commands to run fuzz tests for header and frame parsing.

```console
$ cargo install force cargo-fuzz
$ cargo +nightly fuzz run fuzz_parse_header
$ cargo +nightly fuzz run fuzz_parse_frame
```

--------------------------------

### Setup and Cleanup Network Namespaces

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Scripts to set up and tear down network namespaces for testing Lightway's client-server architecture. The setup script creates namespaces for server, middle, and client, simulating network paths, while the delete script cleans them up.

```bash
sudo ./tests/setup.sh
```

```bash
sudo ./tests/setup.sh delete
```

```bash
sudo env EXTRA_CLIENTS=3 ./tests/setup.sh
```

--------------------------------

### htpasswd User Creation Example

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Example of creating a user and password hash using the htpasswd command for Lightway server authentication. It highlights the use of the -B option for bcrypt hashing.

```console
$ htpasswd -B -c lwpasswd my_user
New password:
Re-type new password:
Adding password for user my_user
$ cat lwpasswd
my_user:$2y$05$V6da9E.ys3QUnhgAfSGm6eM5dhkHa6Oc90kKNpb8bmcCgPsreU7Sa
```

--------------------------------

### Lightway Client Configuration

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Shows how to start the Lightway client using a configuration file. It also mentions that configuration can be overridden via environment variables (prefix LW_CLIENT_) or command-line arguments. The `--inside-mtu` option requires CAP_SYS_ADMIN capability.

```bash
lightway-client --config-file './tests/client/client_config.yaml'
```

--------------------------------

### Lightway Server Configuration

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Demonstrates how to start the Lightway server with a configuration file and override the log level using environment variables or command-line arguments. Environment variables have lower priority than command-line arguments.

```bash
LW_SERVER_LOG_LEVEL=trace lightway-server --config-file './tests/server/server_config.yaml'
```

```bash
LW_SERVER_LOG_LEVEL=trace lightway-server --config-file './tests/server/server_config.yaml' --log-level=off
```

--------------------------------

### Build and Test with Earthly

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Commands to build and test the Lightway project using Earthly. Earthly allows building without a full local development environment setup.

```bash
earthly +build
```

```bash
earthly +test
```

--------------------------------

### E2E Testing with Earthly

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Provides commands for running all end-to-end tests or a single test using Earthly. It also shows how to start the test stack using Docker Compose and access containers.

```bash
earthly --allow-privileged +e2e
```

```bash
earthly --allow-privileged ./tests+run-tcp-test
```

```bash
earthly -P ./tests/+save-all-test-containers  && SERVER_ARGS="--config-file server_config.yaml" CLIENT_ARGS="--config-file client_config.yaml" docker compose -f tests/e2e/docker-compose.yml up
```

```bash
docker compose -f tests/e2e/docker-compose.yml exec client bash
```

--------------------------------

### IP Address Filter Plugin Example (Rust)

Source: https://github.com/expressvpn/lightway/blob/main/docs/plugins.md

An example implementation of a Lightway plugin (`IpFilter`) that filters packets based on IP addresses. It drops ingress packets destined for a specified IP and egress packets originating from it. The example includes the `IpFilter` struct, its `Plugin` implementation, and a `PluginFactory` for creating instances of the filter.

```rust
use std::net::Ipv4Addr;
use bytes::BytesMut;
use lightway_core::{Plugin, PluginType, PluginFactory, PluginResult, PluginFactoryError};
use pnet::packet::ipv4::Ipv4Packet;

#[derive(Clone, Debug)]
struct IpFilter(Ipv4Addr);

impl IpFilter {
    fn new(ip: Ipv4Addr) -> Self {
        Self(ip)
    }
}

impl Plugin for IpFilter {
    fn ingress(&self, data: &mut BytesMut) -> PluginResult {
        let Some(packet) = Ipv4Packet::new(data) else {
            return PluginResult::Accept;
        };
        if packet.get_destination() == self.0 {
            PluginResult::Drop
        } else {
            PluginResult::Accept
        }
    }

    fn egress(&self, data: &mut BytesMut) -> PluginResult {
        let Some(packet) = Ipv4Packet::new(data) else {
            return PluginResult::Accept;
        };
        if packet.get_source() == self.0 {
            PluginResult::Drop
        } else {
            PluginResult::Accept
        }
    }
}

pub struct IpFilterPluginFactory {
    filter: IpFilter
}

impl IpFilterPluginFactory {
    pub fn new(ip: Ipv4Addr) -> Self {
        let filter = IpFilter::new(ip);
        Self { filter }
    }
}

impl PluginFactory for IpFilterPluginFactory {
    fn build(&self) -> Result<PluginType, PluginFactoryError> {
        let filter = self.filter.clone();
        Ok(Box::new(filter))
    }
}
```

--------------------------------

### Rust Fuzzing Setup Note

Source: https://github.com/expressvpn/lightway/blob/main/lightway-core/README.md

A note regarding the incompatibility of `cargo fuzz` with LTO and the necessary workaround in `Cargo.toml`.

```rust
// Comment out the following line in workspace's Cargo.toml:
// lto = true
```

--------------------------------

### Building and Running with Nix

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Demonstrates how to build and run the Lightway server and client using Nix commands. It also covers setting up a development environment and using a nightly toolchain for fuzzing.

```nix
nix build .#lightway-server
```

```nix
nix build .#lightway-client
```

```nix
nix run .#lightway-server -- -c config.yaml
```

```nix
nix run .#lightway-client -- -c config.yaml
```

```nix
nix develop
```

```nix
cargo build --bin lightway-server
```

```nix
nix develop .#nightly
```

--------------------------------

### PacketEncoder Trait

Source: https://github.com/expressvpn/lightway/blob/main/docs/inside_packet_codec.md

Defines the interface for encoding inside packets in Lightway. It includes methods to store packets, get the encoding state, and set the encoding state.

```rust
/// [`PacketEncoder`] trait. Accumulates inside packets and turn them to encoded packets
pub trait PacketEncoder {
    /// Store one inside packet into the [`PacketEncoder`]
    ///
    /// Returns a [`CodecStatus`].
    /// If the status is [`CodecStatus::PacketAccepted`], the packet is accepted by the encoder.
    /// If the status is [`CodecStatus::SkipPacket`], the packet is skipped by the encoder and lightway
    /// may send it as a normal wire::Data packet.
    fn store(&self, data: &mut BytesMut) -> PacketCodecResult<CodecStatus>;

    /// Get the encoding state
    ///
    /// The returned bool indicates whether encoding is enabled.
    fn get_encoding_state(&self) -> bool;

    /// Set the encoding status
    ///
    /// The param indicates whether encoding is enabled or disabled.
    fn set_encoding_state(&self, enabled: bool);
}
```

--------------------------------

### Earthly Documentation Target

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Command to view available Earthly targets and documentation.

```bash
earthly doc
```

--------------------------------

### Code Formatting

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Command to format the Rust code according to standard practices.

```bash
cargo fmt
```

--------------------------------

### Modify Client Source Address

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Changes the source IP address of the client's network interface within its namespace, useful for testing different network configurations or simulating specific client setups.

```bash
sudo ip netns exec lightway-client ip addr add 192.168.0.3/24 dev veth
sudo ip netns exec lightway-client ip addr del 192.168.0.2/24 dev veth
```

--------------------------------

### Mixed Configuration Handling

Source: https://github.com/expressvpn/lightway/blob/main/docs/parallel_connect.md

Demonstrates how the client prioritizes the 'servers' array, ignoring legacy parameters when the array is present.

```yaml
# This configuration uses only the servers array
servers:
  - server: primary.example.com:443
    mode: tcp
    server_dn: primary.example.com
    cipher: aes256

# These legacy parameters are ignored when servers array is present
server: ignored.example.com:443
mode: udp
server_dn: ignored.example.com
```

--------------------------------

### Test PROXY Protocol with Lightway Server

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Demonstrates how to test the Lightway server's PROXY protocol support by setting up a Python-based PROXY protocol frontend that forwards traffic to the Lightway server.

```bash
python3 -m venv --prompt proxy-protocol proxy-protocol
./proxy-protocol/bin/pip3 install proxy-protocol
sudo ip netns exec lightway-server ./proxy-protocol/bin/proxyprotocol-server --service 0.0.0.0:443 '[::1]:443'
```

--------------------------------

### Lightway Server Configuration Options

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Details on how Lightway server configuration can be overridden using environment variables or CLI arguments. Environment variables require the LW_SERVER_ prefix and uppercase, while CLI arguments use lowercase with hyphens.

```APIDOC
Lightway Server Configuration:

Configuration can be managed via a config file, environment variables, or CLI arguments.

- **Config File**: Specified using the `--config-file` argument.
- **Environment Variables**: Prefix with `LW_SERVER_`. Use uppercase and underscores for word separation (e.g., `LW_SERVER_PORT`).
- **CLI Arguments**: Use lowercase and hyphens for word separation (e.g., `--port`). CLI arguments have the highest priority.

**Authentication Methods:**

1.  **Username / Password**: 
    - Uses a user database compatible with Apache htpasswd files.
    - Hashing algorithms supported by the `pwhash` crate are required (e.g., bcrypt using `-B`, `-2`, or `-5` flags with `htpasswd`).
    - **Caution**: Avoid passing passwords directly via CLI (`--password`) due to security risks. Use config files or environment variables (`LW_CLIENT_PASSWORD`).

2.  **JWT Token**: 
    - Requires an RSA public key provided via `token_rsa_pub_key_pem`.
    - Tokens must use the "RS256" algorithm and include "exp" (expiration) claim in the payload.
    - Header must include `{"alg": "RS256", "typ": "JWT"}`.
    - Payload must include `{"exp": <timestamp>}`.
    - Keys and tokens can be generated using standard RSA and JWT tooling (e.g., mkjwk.org, jwt.io).
```

--------------------------------

### Enable WolfSSL Debug Logging

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Activates WolfSSL's detailed debug logging for both Lightway client and server when compiled with the 'debug' feature. This provides verbose output for troubleshooting TLS-related issues.

```bash
cargo run --features debug --bin lightway-client -- --tls-debug
cargo run --features debug --bin lightway-server -- --tls-debug
```

--------------------------------

### Test Network Connectivity within Client Namespace

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Enters the lightway-client network namespace and attempts to ping google.com to verify network connectivity through the Lightway tunnel.

```bash
sudo ip netns exec lightway-client bash
ping google.com -c 3
```

--------------------------------

### Create Fuzzing Corpus for Frame Parsing

Source: https://github.com/expressvpn/lightway/blob/main/lightway-core/README.md

Creates a corpus of valid frames for fuzzing the `fuzz_parse_frame` target. Each command creates a file with specific byte sequences representing different frame types.

```console
$ printf "\x01" > corpus/fuzz_parse_frame/noop
$ printf "\x02\xf0\x0b\xbe\xed" > corpus/fuzz_parse_frame/ping
$ printf "\x03\xab\xcd\xef\x09" > corpus/fuzz_parse_frame/pong
$ printf "\x04\x01\x02\x06mesecret" > corpus/fuzz_parse_frame/auth_request_userpass
$ printf "\x04\x17\x00\x04\x01\x02\x03\x04" > corpus/fuzz_parse_frame/auth_request_custom_callback
$ printf "\x05\x00\x03\xfe\xbe\xaa" > corpus/fuzz_parse_frame/data
$ printf "\x061.1.1.1\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x002.2.2.2\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x003.3.3.3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x001500\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x2f\x66" > corpus/fuzz_parse_frame/auto_success_with_config_v4
$ printf "\x07\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" > corpus/fuzz_parse_frame/auth_failure
$ printf "\x0c" > corpus/fuzz_parse_frame/goodbye
$ printf "\x0e\x00\x0dserver config" > corpus/fuzz_parse_frame/server_config
```

--------------------------------

### Configure Log Format

Source: https://github.com/expressvpn/lightway/blob/main/docs/logs_and_metrics.md

Specifies the output format for Lightway logs. Supported formats include 'json', 'compact', and 'pretty'. Configured using the `--log-format` command-line argument.

```bash
./lightway-server --config ./server.yaml --log-format json
```

--------------------------------

### Legacy Single Server Configuration

Source: https://github.com/expressvpn/lightway/blob/main/docs/parallel_connect.md

Illustrates the backward-compatible single-server configuration parameters, used when the 'servers' array is not provided or is empty.

```yaml
# Legacy single-server configuration (still supported)
server: example.com:443
mode: tcp
server_dn: example.com
cipher: aes256
tun_name: lightway
tun_local_ip: 100.64.0.6
tun_peer_ip: 100.64.0.5
tun_dns_ip: 100.64.0.1
```

--------------------------------

### Run Wireshark within a Network Namespace

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Launches Wireshark as the current user within a specified network namespace, allowing for network traffic analysis in an isolated environment.

```bash
sudo -E ip netns exec lightway-client su -c wireshark $USER
```

--------------------------------

### Single Server Configuration (Before)

Source: https://github.com/expressvpn/lightway/blob/main/docs/parallel_connect.md

This YAML snippet represents the 'before' state of a single server configuration, detailing server address, connection mode, server distinguished name, and cipher.

```yaml
server: example.com:443
mode: tcp
server_dn: example.com
cipher: aes256
```

--------------------------------

### Lightway TLS/DTLS Protocol Support Summary

Source: https://github.com/expressvpn/lightway/blob/main/docs/tls_versions.md

This table summarizes the supported TLS and DTLS protocol versions for both the Lightway server and client. It highlights the primary supported versions and any backward compatibility measures.

```markdown
|                 | TLS     | DTLS               |
| --------------- | ------- | ------------------ |
| Lightway Server | TLS 1.3 | DTLS1.2<br>DTLS1.3 |
| Lightway Client | TLS 1.3 | DTLS1.3            |
```

--------------------------------

### Lightway Client and Server Implementations

Source: https://github.com/expressvpn/lightway/blob/main/docs/design_overview.md

These components provide the Linux-specific implementations for the Lightway client and server, enabling full TCP and UDP support. They integrate with the lightway-core library to handle the secure data transmission.

```bash
# Example of how a Linux client might initiate a connection and use lightway-core

# Assume lightway_core is initialized and a connection is established
let mut core = LightwayCore::new();
let connection_id = 0;

# Simulate receiving data from the tun device (inside)
let tun_data = vec![/* raw IP packet bytes */];
let encrypted_packets = core.inside_data_received(&tun_data, connection_id);

# Send encrypted packets over the network socket (outside)
for packet in encrypted_packets {
    send_udp_packet("server_ip", 1194, &packet);
}

# Simulate receiving encrypted data from the network socket (outside)
let received_encrypted_data = receive_udp_packet(1194);
let unwrapped_data = core.outside_data_received(&received_encrypted_data, connection_id);

# Write unwrapped data to the tun device (inside)
write_to_tun_device(&unwrapped_data);

```

--------------------------------

### Configure Log Level

Source: https://github.com/expressvpn/lightway/blob/main/docs/logs_and_metrics.md

Sets the logging verbosity for the Lightway server. Supported levels include 'info', 'debug', etc. Configured using the `--log-level` command-line argument.

```bash
./lightway-server --config ./server.yaml --log-level info
```

--------------------------------

### Server Connection Metrics

Source: https://github.com/expressvpn/lightway/blob/main/docs/logs_and_metrics.md

Metrics related to server-side connection performance and state. Includes timing, packet handling, and session counts.

```APIDOC
to_online_time:
  type: Histogram
  description: Measures time between a connection being started (on first packet) and the connection being online (i.e. authenticated and passing data packets)

tun_rejected_packet_invalid_state:
  type: Counter
  description: Counts packets received on the TUN device for a connection which is not in the Online state

tun_rejected_packet_invalid_inside_packet:
  type: Counter
  description: Counts packets received on the TUN device which are invalid (e.g. too large, not an IPv4)

tun_rejected_packet_invalid_other:
  type: Counter
  description: Counts packets received on the TUN device which are invalid for an uncategorised reason

tun_rejected_packet_no_connection:
  type: Counter
  description: Counts packets received on the TUN device for which there is no corresponding connection

tun_from_client:
  type: Counter
  description: Counts bytes sent on the TUN interface (i.e. which is data coming from a client)

tun_to_client:
  type: Counter
  description: Counts bytes received on the TUN interface (i.e which is data going to a client)

sessions_current_online:
  type: Gauge
  description: The number of connections which are currently in the Online state

sessions_lifetime_total:
  type: Gauge
  description: The total number of connections which have been created over the entire lifetime of the server

sessions_pending_id_rotations:
  type: Gauge
  description: The number of connections for which a session ID rotation is in progress

sessions_active_5m, sessions_active_15m, sessions_active_60m:
  type: Gauge
  description: The number of connections which were “active” in most recent N minutes. An “active” connection is one where traffic has been seen from the client to the Internet

sessions_standby_5m, sessions_standby_15m, sessions_standby_60m:
  type: Gauge
  description: The number of connections which were “on standby” in most recent N minutes. An “on standby” connection is one where traffic has been seen from the Internet to the client

assigned_internal_ips:
  type: Gauge
  description: The current number of IPs which are allocated to connections
```

--------------------------------

### Lightway PMTU Implementation

Source: https://github.com/expressvpn/lightway/blob/main/docs/pmtu_discovery.md

The core implementation of Path MTU Discovery within the Lightway protocol. This Rust code handles the state machine and logic for calculating the Path MTU.

```rust
lightway_core::connection::dplpmtud
```

--------------------------------

### Lightway Protocol Overview

Source: https://github.com/expressvpn/lightway/blob/main/docs/wireshark.md

Provides an overview of the Lightway protocol, its transport mechanisms (UDP and TCP), and its relationship with TLS and D/TLS. It highlights the need for a custom Wireshark plugin for Lightway/UDP traffic due to added headers.

```APIDOC
Lightway Protocol:
  Type: Lightweight VPN protocol from ExpressVPN
  Transport: UDP and TCP
  TCP Mode: Pure TLS stream, decodable as TLS in Wireshark.
  UDP Mode: Based on D/TLS with added custom headers, requiring Wireshark plugin for decoding.

Wireshark Plugin Requirements:
  - For Lightway/UDP traffic.
  - Installation: Copy `lightway.lua` to `~/.local/lib/wireshark/plugins`.
  - Usage: Select `LIGHTWAY-UDP` protocol in Wireshark packet decoder.
  - Auto-decode: Configure `udp_port:add(<PORT>, lightway_protocol)` in the plugin file for custom ports.

Note:
  - Processing large packet capture files with the plugin might be time-consuming.
```

--------------------------------

### Simulate Path MTU Discovery Conditions

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Adjusts the Maximum Transmission Unit (MTU) for network interfaces in the middle and server network namespaces to test Path MTU Discovery behavior, particularly for UDP traffic.

```bash
sudo ip netns exec lightway-middle ip link set mtu 1300 dev veth-s2m
sudo ip netns exec lightway-server ip link set mtu 1300 dev veth-s2m
```

--------------------------------

### Lightway Core Library Overview

Source: https://github.com/expressvpn/lightway/blob/main/docs/design_overview.md

The lightway-core is a multi-platform Rust library responsible for encrypting and processing IP packets. It's designed to be a foundational component, deferring platform-specific I/O operations like UDP packet transmission to the host application.

```rust
/// Represents the core encryption and processing logic for Lightway.
/// This library is platform-agnostic and focuses on the secure wrapping and unwrapping of IP packets.
pub struct LightwayCore {
    // Internal state for encryption, key management, etc.
}

impl LightwayCore {
    /// Initializes a new Lightway core instance.
    pub fn new() -> Self {
        // Initialization logic
        unimplemented!();
    }

    /// Processes data received from the 'inside' (e.g., tun device).
    /// Encrypts the data and returns it for transmission over the network.
    /// 
    /// # Arguments
    /// * `data` - The raw IP packet data.
    /// * `connection_id` - Identifier for the current connection.
    /// 
    /// # Returns
    /// A vector of byte slices representing encrypted packets to be sent 'outside'.
    pub fn inside_data_received(&mut self, data: &[u8], connection_id: usize) -> Vec<Vec<u8>> {
        // Encryption and wrapping logic
        unimplemented!();
    }

    /// Processes data received from the 'outside' (e.g., network socket).
    /// Decrypts the data and returns it for delivery to the 'inside'.
    /// 
    /// # Arguments
    /// * `data` - The encrypted packet data.
    /// * `connection_id` - Identifier for the current connection.
    /// 
    /// # Returns
    /// A vector of byte slices representing unwrapped data to be sent 'inside'.
    pub fn outside_data_received(&mut self, data: &[u8], connection_id: usize) -> Vec<Vec<u8>> {
        // Decryption and unwrapping logic
        unimplemented!();
    }
}

// Host application would provide implementations for:
// trait OutsideIO {
//     fn send(&mut self, data: &[u8]);
// }
// 
// trait InsideIO {
//     fn send(&mut self, data: &[u8]);
// }
```

--------------------------------

### Parallel Connect Configuration (After)

Source: https://github.com/expressvpn/lightway/blob/main/docs/parallel_connect.md

This YAML snippet represents the 'after' state of a configuration that has migrated to a parallel connect model, using a list of servers with their respective modes, server distinguished names, and ciphers.

```yaml
servers:
  - server: example.com:443
    mode: tcp 
    server_dn: example.com
    cipher: aes256
```

--------------------------------

### Lightway Connection State Machine Diagram

Source: https://github.com/expressvpn/lightway/blob/main/docs/connection_state_machine.md

Visual representation of the Lightway connection lifecycle, showing states and transitions. This diagram helps understand the flow from initial connection to being online and eventual disconnection.

```mermaid
stateDiagram-v2
    direction TB
    Connecting: State::Connecting
    LinkUp: State::LinkUp
    Authenticating: State::Authenticating
    Online: State::Online
    Disconnecting: State::Disconnecting
    Disconnected: State::Disconnected

    %% Fake states for clarity in diagram
    AuthFailedDisconnecting: State::Disconnecting

    note left of Connecting
      Secure (D)TLS connection negotiated

      wolfssl::Session::try_negotiate()
      called until success or failure.
    end note

    [*] --> Connecting
    Connecting --> LinkUp: (D)TLS connection is established

    state client_server_auth <<fork>>
        LinkUp --> client_server_auth
        client_server_auth --> ClientAuth: Client:: Begins authenticating
        client_server_auth --> ServerAuth: Server:: Frame::AuthRequest received

    state ClientAuth {
        [*] --> Authenticating
        Authenticating --> [*]: Frame::AuthSuccessWithConfigV4 received
    }

    state ServerAuth {

        state if_state <<choice>>
            [*] --> if_state: Call to ServerAuth::authorize() callback
            if_state
            if_state --> [*]: ServerAuthResult::Granted
            if_state --> AuthFailedDisconnecting: ServerAuthResult::Denied
    }

    state client_server_auth_done <<join>>
        ClientAuth --> client_server_auth_done
        ServerAuth --> client_server_auth_done
        client_server_auth_done --> Online

    Online --> Disconnecting: Connection::disconnect() method called

    Disconnecting --> Disconnected
    Disconnected --> [*]
```

--------------------------------

### Lightway Connection State Transitions

Source: https://github.com/expressvpn/lightway/blob/main/docs/connection_state_machine.md

Describes the Rust code logic for state transitions within the Lightway connection. It highlights how external events or internal checks can lead to changes in the connection's state.

```rust
// Some transitions are ommitted for clarity:
// If no DTLS traffic is received the `Connection::tick()` can transition
// directly to `State::Disconnected` from any state.
// A call to `Connection::disconnect()` will transition to
// `State::Disconnecting`.
```

--------------------------------

### Lightway Server Metrics

Source: https://github.com/expressvpn/lightway/blob/main/docs/logs_and_metrics.md

This section lists and defines the metrics available on the Lightway server. These metrics cover various aspects of server operation, including connection acceptance, TLS handshake, authentication, and UDP packet processing. They are categorized by their source (server or core) and type (Counter or Histogram).

```APIDOC
Metric Name | Source | Metric Type | Definition
---
conn_accept_failed | server | Counter | A new connection could not be accepted
connection_accept_proxy_header_failed | server | Counter | A new connection did cnot present a valid PROXY header
conn_create_failed | server | Counter | A new connection could not be created
conn_alloc_frag_map | core | Counter | A connection has used a fragmented data packet. Therefore the 2M FragmentMap has been allocated
wolfssl_appdata | core | Counter | An AppData result occurred during a WolfSSL operation. Given current configuration we do not expect this to be non-zero
session_id_mismatch | core | Counter | Server has received a mismatched session_id in the header after the packet content has been validated. Should generally be expected to happen rarely
received_encoding_req_non_online | core | Counter | Server received an encoding request when the Connection state is not Online
received_encoding_req_with_tcp | core | Counter | Server received an encoding request when the Connection type is TCP
received_encoding_res_as_server | core | Counter | Server received an encoding response
conn_created | server | Counter | The number of new connections created
conn_link_up | server | Counter | Counts connection which have reached the “link up” state (~(D)TLS connection established)
conn_online | server | Counter | Counts connection which have reached the “online” state after successful authentication
conn_rejected_no_free_ip | server | Counter | Counts connections which were rejected at auth time due to a lack of free IPs in the server pool. Should generally be expected to be 0
conn_rejected_access_denied | server | Counter | Counts connections rejected due to invalid auth
conn_tls_error | server | Counter | Counts connections which failed due to a TLS failure from WolfSSL
conn_unknown_error | server | Counter | Counts connections which failed due to a non-TLS failure from WolfSSL
conn_aged_out | server | Counter | Counts connections which are disconnected due to being idle (after 1 day of inactivity)
user_auth_eviction | server | Counter | Counts connections which are disconnected due to their auth expiring
conn_client_closed | server | Counter | Counts connections which have been closed since client initiate Disconnect
conn_stale_closed | server | Counter | Counts connections which have been closed since it has not become ONLINE within STALE_AGE (60s)
conn_closed | server | Counter | Counts total connections which have been closed for any reason (including client_closed, stale_closed, etc.)
udp_conn_recovered_via_session | server | Counter | Counts UDP connections which have been recovered using the session ID (which indicates that the client’s IP address changed)
udp_session_rotation_attempted_via_replay | server | Counter | Counts UDP rotation attempted using duplicated packets. i.e An attack ie. Some adversary capture and replay packets from different IP address. There is also a possibility that counter is incremented due to aggressive connect.
udp_recv_truncated | server | Counter | Counts occurrences of UDP packet truncation on receive
udp_recv_invalid_addr | server | Counter | Counts failures to retrieve a valid socket address from `recvmsg` syscall
udp_recv_missing_pktinfo | server | Counter | Counts failures to find a valid `PKTINFO` control message in `recvmsg` result
udp_bad_packet_version | server | Counter | Counts UDP packets where the the version in the wire protocol header was not a version supported by the server
udp_rejected_session | server | Counter | Counts UDP packets which were rejected due to the session id in the wire protocol header not being recognised
udp_parse_wire_failed | server | Counter | Counts UDP packets which could not be parsed. Indicates plugin ingress chain failed
udp_no_header | server | Counter | Counts UDP packets where the wire protocol header was not found/could not be found
udp_session_rotation_begin | server | Counter | Counts connections which started a session ID rotation
udp_session_rotation_finalized | server | Counter | Counts connections which completed a session ID rotation
to_link_up_time | server | Histogram | Measures time between a connection being started (on first packet) and the Link Up state (i.e. (D)TLS negotiation complete)
```

--------------------------------

### Decrypt TLS1.3 Data Packets with Keylog File

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Enables the creation of a keylog file during Lightway client execution (with the 'debug' feature) which can be used in Wireshark to decrypt TLS1.3 traffic. This is crucial for debugging encrypted communication.

```bash
cargo run --features debug --bin lightway-client -- --config-file=tests/client_conf.yaml --keylog "/tmp/client.log"
```

--------------------------------

### Monitor Network Traffic with tcpdump

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Executes tcpdump within the lightway-remote network namespace to monitor traffic on the 'wan' interface, useful for verifying packet reception and replies.

```bash
sudo ip netns exec lightway-remote bash
tcpdump -i wan -nvvl
```

--------------------------------

### Lightway Plugin Trait Definition

Source: https://github.com/expressvpn/lightway/blob/main/docs/plugins.md

Defines the core `Plugin` trait for Lightway, outlining the `ingress` and `egress` hooks for controlling packet flow. These hooks receive mutable `BytesMut` data and return a `PluginResult` to indicate whether to accept or drop the packet.

```rust
pub trait Plugin {
    /// Hook to run during packet ingress
    fn ingress(&self, data: &mut BytesMut) -> PluginResult;

    /// Hook to run during packet egress
    fn egress(&self, data: &mut BytesMut) -> PluginResult;
}
```

--------------------------------

### Disable Permissions Checks for Dev Testing

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Sets an environment variable to disable permission checks, which is necessary when running tests as root on a machine where user-owned files are involved.

```bash
export LW_DANGEROUSLY_DISABLE_PERMISSIONS_CHECKS=1
```

--------------------------------

### Parallel Server Configuration

Source: https://github.com/expressvpn/lightway/blob/main/docs/parallel_connect.md

Defines an array of servers for parallel connection attempts. Each server entry includes its address, connection mode, domain name for TLS validation, and cipher.

```yaml
servers:
  - server: primary.example.com:443
    mode: tcp
    server_dn: primary.example.com
    cipher: aes256
  - server: backup.example.com:443
    mode: tcp
    server_dn: backup.example.com
    cipher: aes256
```

--------------------------------

### JWT Token Header Requirements

Source: https://github.com/expressvpn/lightway/blob/main/README.md

Specifies the minimum required header fields for a JWT token used in Lightway authentication.

```json
{
  "alg": "RS256",
  "typ": "JWT"
}
```