18 KiB
title | weight | next | prev | cascade | ||
---|---|---|---|---|---|---|
Running RF Swift | 1 | /docs/guide/list-of-images/ | /docs/quick-start |
|
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.
{{< callout type="warning" >}}
On Linux, unless you are using Docker Desktop, you will need to use sudo
with the rfswift
command for operations that require elevated privileges.
{{< /callout >}}
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.
{{< callout type="info" >}} 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 {{< /callout >}}
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:
{{< tabs items="Linux,Windows,macOS" >}} {{< tab >}}
cat /home/username/.config/rfswift/config.ini
[general]
imagename = myrfswift:latest
...
{{< /tab >}} {{< tab >}}
type C:\Users\username\AppData\Roaming\rfswift\config.ini
[general]
imagename = myrfswift:latest
...
{{< /tab >}} {{< tab >}}
cat /Users/username/.config/rfswift/config.ini
[general]
imagename = myrfswift:latest
...
{{< /tab >}} {{< /tabs >}}
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
{{< callout type="info" >}} 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. {{< /callout >}}
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
{{< callout type="warning" >}}
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.
{{< /callout >}}
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
{{< callout type="info" >}} 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. {{< /callout >}}
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
{{< callout type="warning" >}} GUI applications require:
- Linux:
xhost
installed and configured - macOS:
XQuartz
properly configured - Windows: Native support via Docker Desktop {{< /callout >}}
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
{{< callout type="info" >}}
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.
{{< /callout >}}
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
{{< callout type="warning" >}} 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. {{< /callout >}}