467 lines
18 KiB
Markdown
467 lines
18 KiB
Markdown
---
|
||
title: Running RF Swift
|
||
weight: 1
|
||
next: /docs/guide/list-of-images/
|
||
prev: /docs/quick-start
|
||
cascade:
|
||
type: docs
|
||
---
|
||
|
||
# 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`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
[!] 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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 >}}
|
||
```bash
|
||
cat /home/username/.config/rfswift/config.ini
|
||
[general]
|
||
imagename = myrfswift:latest
|
||
...
|
||
```
|
||
{{< /tab >}}
|
||
{{< tab >}}
|
||
```powershell
|
||
type C:\Users\username\AppData\Roaming\rfswift\config.ini
|
||
[general]
|
||
imagename = myrfswift:latest
|
||
...
|
||
```
|
||
{{< /tab >}}
|
||
{{< tab >}}
|
||
```bash
|
||
cat /Users/username/.config/rfswift/config.ini
|
||
[general]
|
||
imagename = myrfswift:latest
|
||
...
|
||
```
|
||
{{< /tab >}}
|
||
{{< /tabs >}}
|
||
|
||
With the default tag set, you can simplify the `run` command:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
rfswift run -i sdr_full -n my_sdr_container
|
||
```
|
||
|
||
#### Container Listing and Selection
|
||
|
||
If you forget container names, use the `last` command:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
rfswift exec
|
||
```
|
||
|
||
To restart a specific container by name:
|
||
|
||
```bash
|
||
rfswift exec -c my_sdr_container
|
||
```
|
||
|
||
#### Container Lifecycle Management
|
||
|
||
**Save container changes as a new image:**
|
||
```bash
|
||
rfswift commit -c my_container -i my_new_image
|
||
```
|
||
|
||
**Rename a container:**
|
||
```bash
|
||
rfswift rename -n old_name -d new_name
|
||
```
|
||
|
||
**Remove a container:**
|
||
```bash
|
||
rfswift remove -c container_name
|
||
```
|
||
|
||
**Delete an image:**
|
||
```bash
|
||
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**):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```bash
|
||
┌─[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:
|
||
|
||
```ini
|
||
[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**:
|
||
```bash
|
||
# 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**:
|
||
```bash
|
||
# 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**:
|
||
```bash
|
||
# 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:**
|
||
|
||
```bash
|
||
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:**
|
||
|
||
1. **Run with specific privileges and capabilities**:
|
||
```bash
|
||
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.
|
||
|
||
2. **Add custom cgroup rules and device mappings**:
|
||
```bash
|
||
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.
|
||
|
||
3. **Set a custom seccomp profile**:
|
||
```bash
|
||
rfswift run -i penthertz/rfswift:security -n forensics -m ~/custom_seccomp.json
|
||
```
|
||
This applies a custom seccomp profile to the container.
|
||
|
||
4. **Combined security settings**:
|
||
```bash
|
||
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 >}} |