Documentation

📖 Guide

Running RF Swift

Important settings

RF Swift provides a streamlined command-line interface to manage containers for RF and hardware security applications. This guide covers essential commands and workflows.

⚠️

On Linux, unless you are using Docker Desktop, you will need to use sudo with the rfswift command for operations that require elevated privileges.

Command Overview

Let’s explore the available commands with rfswift --help:

rfswift --help
[...]                                                                                                                                              


  888~-_   888~~        ,d88~~\                ,e,   88~\   d8   
  888   \  888___       8888    Y88b    e    /  "  _888__ _d88__ 
  888    | 888          'Y88b    Y88b  d8b  /  888  888    888   
  888   /  888           'Y88b,   Y888/Y88b/   888  888    888   
  888_-~   888             8888    Y8/  Y8/    888  888    888   
  888 ~-_  888          \__88P'     Y    Y     888  888    "88_/       

                RF toolbox for HAMs and professionals                                                                             

rfswift is THE toolbox for any HAM & radiocommunications and hardware professionals

Usage:
  rfswift [flags]
  rfswift [command]

Available Commands:
  bindings    Manage devices and volumes bindings
  commit      Commit a container
  completion  Generate the autocompletion script for the specified shell
  delete      Delete an rfswift images
  exec        Exec a command
  help        Help about any command
  host        Host configuration
  images      RF Swift images management remote/local
  install     Install function script
  last        Last container run
  remove      Remove a container
  rename      Rename a container
  retag       Rename an image
  run         Create and run a program
  stop        Stop a container
  update      Update RF Swift

Flags:
  -q, --disconnect   Don't query updates (disconnected mode)
  -h, --help         help for rfswift

Use "rfswift [command] --help" for more information about a command.

ℹ️

Privilege requirements by platform:

Linux: sudo is required for most container operations when not using Docker Desktop
Windows/macOS: With Docker Desktop or OrbStack, sudo is not necessary
Windows: Commands related to USB binding require Administrator privileges

Core Workflows

1. Keeping RF Swift Updated

RF Swift automatically checks for updates when launched:

[!] You are running version: 0.4.8 (Obsolete)
[+] Do you want to update to the latest version? (yes/no):

You can also trigger updates manually:

rfswift update

[!] Your current version (0.4.8) is obsolete. Please update to version (v0.6.0).
[+] Do you want to update to the latest version? (yes/no): yes
Latest release download URL: https://github.com/PentHertz/RF-Swift/releases/download/v0.6.0/rfswift_linux_amd64
[+] Do you want to replace the existing binary with this new release? (yes/no): yes
13.67 MiB / 13.67 MiB [---------------------------------------------------------------------------------------------------------------------------------------------------------------------------] 100.00%%
File downloaded and replaced successfully.

2. Image Management

Customizing Image Tags

You can rename image tags for convenience or to match your default configuration:

rfswift retag -i penthertz/rfswiftdev:sdr_full_amd64 -t myrfswift:latest
[+] You are running version: 0.4.9 (Up to date)
[+] Image renamed!

This allows you to use the default tag in your configuration file:

cat /home/username/.config/rfswift/config.ini
[general]
imagename = myrfswift:latest
...

type C:\Users\username\AppData\Roaming\rfswift\config.ini
[general]
imagename = myrfswift:latest
...

cat /Users/username/.config/rfswift/config.ini
[general]
imagename = myrfswift:latest
...

With the default tag set, you can simplify the run command:

rfswift run -n my_container  # Equivalent to: rfswift run -i myrfswift:latest -n my_container

ℹ️

Changing an image’s tag makes it a “custom” image in RF Swift, which means it won’t receive automatic updates from the official registry.

3. Container Management

Creating and Running Containers

Create a new container from an image:

rfswift run -i sdr_full -n my_sdr_container

Container Listing and Selection

If you forget container names, use the last command:

rfswift last
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ℹ️  Up-to-date                                                                                    │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ You are running the latest version: 0.6.0-dev                                                    │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
  🤖 Last Run Containers                                                                                                                   
┌───────────────────────────┬─────────────────────────────┬───────────────────────────────────────────────────────┬──────────────┬──────────┐
│ Created                   │ Image Tag (ID)              │ Container Name                                        │ Container ID │ Command  │
├───────────────────────────┼─────────────────────────────┼───────────────────────────────────────────────────────┼──────────────┼──────────┤
│ 2025-04-11T16:47:02+02:00 │ penthertz/rfswift:hardware  │ hardware                                              │ b6e43a87e1f6 │ /bin/zsh │
├───────────────────────────┼─────────────────────────────┼───────────────────────────────────────────────────────┼──────────────┼──────────┤
│ 2025-04-11T16:23:43+02:00 │ penthertz/rfswift:bluetooth │ missionbluetooth                                      │ 3d92cb59560f │ /bin/zsh │
├───────────────────────────┼─────────────────────────────┼───────────────────────────────────────────────────────┼──────────────┼──────────┤
│ 2025-04-11T16:18:22+02:00 │ penthertz/rfswift:rfid      │ missionrfid2                                          │ 50cbccef53f5 │ /bin/zsh │
├───────────────────────────┼─────────────────────────────┼───────────────────────────────────────────────────────┼──────────────┼──────────┤
...

Restarting Existing Containers

To restart the most recently used container:

rfswift exec

To restart a specific container by name:

rfswift exec -c my_sdr_container

Container Lifecycle Management

Save container changes as a new image:

rfswift commit -c my_container -i my_new_image

Rename a container:

rfswift rename -n old_name -d new_name

Remove a container:

rfswift remove -c container_name

Delete an image:

rfswift delete -c penthertz/rfswift:tag_name

4. Device and Resource Management

Audio Support

RF Swift will warn if audio support is not properly configured:

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ⚠️  Warning                                                                                       │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Warning: Unable to connect to Pulse server at 127.0.0.1:34567                                    │
...
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

Enable audio support (run without sudo):

rfswift host audio enable
[+] Successfully loaded module-native-protocol-tcp with index 29

Dynamic Device and Volume Binding

One of RF Swift’s most powerful features is the ability to add or remove device bindings to running containers:

# Add a USB device to an existing container
rfswift bindings add -c my_container -d -s /dev/ttyUSB0:/dev/ttyUSB0

# For some destination, use shortcuts with -t only
rfswift bindings add -c my_container -d -t /dev/ttyUSB0

# Add a shared folder
rfswift bindings add -c my_container -b ~/projects:/root/projects

# Remove a binding
rfswift bindings rm -c my_container -t /dev/ttyUSB0 [-d]

# List current bindings
rfswift bindings list -c my_container

Don’t forget the -d switch if you want to deal with devices and not volumes.

5. Network Configuration

RF Swift supports various network isolation modes:

Mode	Description
`host`	No network isolation (default)
`bridge`	Default Docker network driver with isolation
`none`	Complete network isolation
`overlay`	Connect multiple Docker daemons
`ipvlan`	Full IPv4/IPv6 addressing control
`macvlan`	Assign MAC addresses to containers

Example of using bridge mode with port mapping:

rfswift run -i bluetooth -n my_container -t bridge -z 8000 -w 8000:127.0.0.1:80/tcp

This command:

Uses the -t bridge option to enable bridge networking
Maps container port 8000 to host port 80 on localhost with -w 8000:127.0.0.1:80/tcp
Exposes port 8000 to other containers with -z 8000

⚠️

For Wi-Fi and Bluetooth tools, you may need to add the NET_ADMIN capability: rfswift run -i wifi_tools -n my_container -a NET_ADMIN Be cautious when adding capabilities as they increase security risks if the container is compromised.

Container Architecture Benefits

graph TD;
    A[Core build]-->B[Image 1];
    A-->C[Docker image 2];
    B-->D[Container #1 from image 1];
    B-->E[Container #2 from image 1];
    C-->F[Container from image 2]

This architecture provides significant advantages:

Portability: Move environments between systems easily
Isolation: Create separate environments for different tasks
Disposability: Create, experiment with, and destroy environments without impact
Specialization: Tailored environments for specific assessment needs
Efficiency: No need to reinstall entire systems
Performance: Less resource-intensive than VMs
Time-saving: Quick deployment for last-minute assessment preparations

ℹ️

RF Swift significantly flattens the Docker learning curve while providing powerful features like dynamic device binding and host resource integration that would otherwise require considerable Docker expertise.

Using RF Tools

Once your container is running, you can use any included RF tools. For example, with an SDR device connected:

┌─[root@topms] - [~] - [Tue Sep 03, 15:15]
└─[$]> sdrangel

⚠️

GUI applications require:

Linux: xhost installed and configured
macOS: XQuartz properly configured
Windows: Native support via Docker Desktop

Advanced Features

Host Isolation

RF Swift implements host isolation through several security mechanisms configured in your config.ini file:

[container]
privileged = false
caps =
seccomp =
cgroups = c 189:* rwm,c 166:* rwm,c 188:* rwm

Default Security Configuration

By default, RF Swift runs containers in unprivileged mode with specific cgroup restrictions:

Unprivileged Mode: Containers run without full root privileges on the host (privileged = false)
Cgroup Restrictions: Controlled device access through character device major numbers:
- c 189:* rwm: Access to USB serial devices (ttyUSB*)
- c 166:* rwm: Access to ACM devices (ttyACM*)
- c 188:* rwm: Access to USB serial converters

This provides a reasonable balance between functionality and security for RF applications.

Customizing Security Settings

You can customize security settings both in the config file and via command-line parameters:

Adding Capabilities:

# Via command line
rfswift run -i sdr_full -n my_container -a NET_ADMIN,SYS_PTRACE

# Via config.ini
caps = NET_ADMIN,SYS_PTRACE

Custom Seccomp Profile:

# Via command line
rfswift run -i sdr_full -n my_container -m /path/to/seccomp.json

# Via config.ini
seccomp = /path/to/seccomp.json

Additional Cgroup Rules:

# Via command line
rfswift run -i sdr_full -n my_container -g "c 226:* rwm"

# Via config.ini
cgroups = c 189:* rwm,c 166:* rwm,c 188:* rwm,c 226:* rwm

ℹ️

Cgroup rules use the format type major:minor permission where:

type is c (character) or b (block)
major:minor defines the device number (use * for wildcard)
permission is r (read), w (write), m (mknod)

For example, c 189:* rwm grants full access to all devices with major number 189.

Command-Line Security Configuration

RF Swift allows you to override or extend security settings directly from the command line when running containers. This is particularly useful for one-off tasks or testing configurations before adding them to your config file.

Complete List of Security-Related Flags:

rfswift run [options]

Security Options:
  -u, --privileged int        Set privilege level (1: privileged, 0: unprivileged)
  -a, --capabilities string   Extra capabilities (separate with commas)
  -g, --cgroups string        Extra cgroup rules (separate with commas)
  -m, --seccomp string        Set Seccomp profile ('default' one used by default)
  -s, --devices string        Extra devices mapping (separate with commas)
  
Network Options:  
  -t, --network string        Network mode (default: 'host')
  -z, --exposedports string   Exposed ports
  -w, --bindedports string    Ports to bind between host and container
  -x, --extrahosts string     Set extra hosts (default: 'pluto.local:192.168.1.2')
  
Resource Options:
  -b, --bind string           Extra volume bindings (separate with commas)
  -d, --display string        Set X Display (default "DISPLAY=:0")
  -p, --pulseserver string    PULSE SERVER TCP address (default "tcp:127.0.0.1:34567")

Examples of Command-Line Security Configurations:

Run with specific privileges and capabilities:
```
rfswift run -i penthertz/rfswift:wifi -n wifi_tools -u 0 -a NET_ADMIN,NET_RAW
```
This runs a container in unprivileged mode but adds the NET_ADMIN and NET_RAW capabilities.
Add custom cgroup rules and device mappings:
```
rfswift run -i penthertz/rfswift:sdr -n rtlsdr -g "c 226:* rwm" -s "/dev/rtlsdr0:/dev/rtlsdr0"
```
This adds permission for device major number 226 and maps a specific RTL-SDR device.
Set a custom seccomp profile:
```
rfswift run -i penthertz/rfswift:security -n forensics -m ~/custom_seccomp.json
```
This applies a custom seccomp profile to the container.
Combined security settings:
```
rfswift run -i penthertz/rfswift:bluetooth -n bt_scanner \
  -t bridge \
  -a NET_ADMIN \
  -g "c 226:* rwm,c 116:* rwm" \
  -s "/dev/bluetooth:/dev/bluetooth" \
  -u 0
```
This creates a container with:
- Bridge networking mode
- NET_ADMIN capability
- Custom cgroup rules for devices with major numbers 226 and 116
- Specific Bluetooth device mapping
- Unprivileged mode

⚠️

Command-line settings always take precedence over config file settings. When using both, command-line options will extend or override the corresponding settings in your config.ini file.

Last updated on April 14, 2025

🚀 Quick Start Container Images