Skip to main content

Service Management Guide

This guide covers managing the FIDO Bridge daemon service, including status monitoring, log viewing, and service control.

Overview​

FIDO Bridge runs as a systemd user service that:

  • Starts automatically on user login
  • Runs in the background as a daemon
  • Provides a D-Bus interface for management
  • Polls for messages from paired devices
  • Manages virtual UHID FIDO device

The service is managed through the fido-bridge CLI tool or standard systemd commands.

Service Management Commands​

All service management commands communicate with the daemon through D-Bus and do not require root privileges.

Check Service Status​

View the current status of the FIDO Bridge service:

fido-bridge status

Source: /path/to/fido-bridge/crates/client/src/commands/status.rs (lines 6-45)

What it shows:

  • Service state (running/stopped)
  • Device ID
  • Server mode (embedded/remote)
  • Server URL
  • Number of paired devices
  • Number of active pairing sessions

Example output:

FIDO Bridge Service Status

Status: running
Device ID: linux-a1b2c3d4e5f6
Server Mode: embedded
Server URL: http://localhost:3000
Paired Devices: 2
Active Sessions: 0

Implementation: Calls D-Bus method GetStatus() on org.fidobridge.Client interface (see /path/to/fido-bridge/crates/client/src/dbus_interface.rs lines 420-450).

View Service Logs​

Display systemd journal logs for the service:

# Show last 50 log entries
fido-bridge logs

# Follow logs in real-time
fido-bridge logs --follow
fido-bridge logs -f

Source: /path/to/fido-bridge/crates/client/src/commands/logs.rs (lines 4-23)

What it does:

  • Without --follow: Shows last 50 log entries
  • With --follow: Continuously streams new log entries (like tail -f)

Implementation: Executes journalctl --user -u fido-bridge with appropriate flags:

  • Default: journalctl --user -u fido-bridge -n 50
  • Follow: journalctl --user -u fido-bridge -f

Example output:

Dec 06 10:30:15 hostname fido-bridge[1234]: [INFO] FIDO Bridge Service starting...
Dec 06 10:30:15 hostname fido-bridge[1234]: [INFO] Device ID: linux-a1b2c3d4e5f6
Dec 06 10:30:15 hostname fido-bridge[1234]: [INFO] D-Bus service registered
Dec 06 10:30:15 hostname fido-bridge[1234]: [INFO] UHID FIDO device started successfully
Dec 06 10:30:15 hostname fido-bridge[1234]: [INFO] FIDO Bridge Service is running

Restart Service​

Restart the FIDO Bridge service:

fido-bridge restart

Source: /path/to/fido-bridge/crates/client/src/commands/restart.rs (lines 5-39)

What it does:

  1. Executes systemctl --user restart fido-bridge
  2. Waits 2 seconds for service to start
  3. Checks service status with systemctl --user is-active fido-bridge
  4. Displays success or warning message

Use cases:

  • Configuration changes requiring reload
  • Service is unresponsive
  • Clearing stuck state
  • Applying updates after binary replacement

Diagnose Installation Issues​

Run comprehensive diagnostics:

fido-bridge diagnose

Source: /path/to/fido-bridge/crates/client/src/commands/install.rs (lines 432-636)

What it checks:

  1. Service Status:

    • Service running: systemctl --user is-active fido-bridge
    • Service enabled: systemctl --user is-enabled fido-bridge

  2. D-Bus Interface:

    • Interface availability: Checks busctl --user list for org.fidobridge.Client

  3. UHID Device Access:

    • /dev/uhid exists
    • File permissions (mode and group)
    • ACL permissions for current user
    • Checks for user:$USER:rw ACL entry

  4. Configuration:

    • Config file exists at ~/.config/fido-bridge/config.toml
    • Displays location

  5. Binary Installation:

    • Binary exists at ~/.local/bin/fido-bridge
    • Binary directory in PATH

Example output:

FIDO Bridge Diagnostics

Service Status:
  Service running: ✓ Yes
  Service enabled: ✓ Yes

D-Bus Interface:
  Interface available: ✓ Yes

UHID Device Access:
  /dev/uhid exists: ✓ Yes
  Permissions: 660
  Group: input
  UHID ACL permissions: ✓ ACL set for username

Configuration:
  Config file: ✓ Exists
  Location: /home/username/.config/fido-bridge/config.toml

Binary Installation:
  Binary installed: ✓ Yes
  Location: /home/username/.local/bin/fido-bridge
  In PATH: ✓ Yes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: Service is running normally
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Direct systemctl Commands​

You can also use standard systemctl commands:

Check Service Status​

systemctl --user status fido-bridge

Shows detailed status including:

  • Process ID (PID)
  • Memory usage
  • Active state
  • Recent log entries

Start Service​

systemctl --user start fido-bridge

Stop Service​

systemctl --user stop fido-bridge

Enable Auto-start​

systemctl --user enable fido-bridge

Service will start automatically on user login.

Disable Auto-start​

systemctl --user disable fido-bridge

Restart Service​

systemctl --user restart fido-bridge

Reload systemd Configuration​

After manually editing the service file:

systemctl --user daemon-reload

Service Configuration​

Service File Location​

User service: ~/.config/systemd/user/fido-bridge.service

Source: /path/to/fido-bridge/install/fido-bridge.service.template

Service File Contents​

[Unit]
Description=FIDO Bridge Service - Secure FIDO device pairing daemon
Documentation=https://github.com/0xc9c3/fido-bridge
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/home/username/.local/bin/fido-bridge daemon
Restart=on-failure
RestartSec=5s

# Environment
Environment="RUST_LOG=warn,fido_bridge=info"

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=%h/.config/fido-bridge

# Resource limits
LimitNOFILE=65536

[Install]
WantedBy=default.target

Modifying Service Configuration​

  1. Edit the service file:

    nano ~/.config/systemd/user/fido-bridge.service

  2. Reload systemd:

    systemctl --user daemon-reload

  3. Restart service:

    systemctl --user restart fido-bridge

Common Configuration Changes​

Change Log Level​

Edit the Environment line:

# Debug logging
Environment="RUST_LOG=debug"

# Info logging (default)
Environment="RUST_LOG=warn,fido_bridge=info"

# Minimal logging
Environment="RUST_LOG=error"

Modify Restart Behavior​

# Restart on any failure (default)
Restart=on-failure
RestartSec=5s

# Always restart
Restart=always
RestartSec=10s

# Never restart
Restart=no

Adjust Resource Limits​

# Increase file descriptor limit
LimitNOFILE=131072

# Add memory limit
LimitMEMLOCK=64M

Signal Handling​

The daemon handles POSIX signals gracefully.

Source: /path/to/fido-bridge/crates/client/src/daemon.rs (lines 16-30, 82-85)

SIGTERM / SIGINT (Ctrl+C)​

# Send SIGTERM
systemctl --user stop fido-bridge

# Or with kill
kill -TERM $(pgrep -u $USER fido-bridge)

Behavior: Graceful shutdown

  1. Logs "Received termination signal, shutting down gracefully..."
  2. Closes signal handlers
  3. Stops embedded server (if running)
  4. Exits cleanly

SIGHUP​

kill -HUP $(pgrep -u $USER fido-bridge)

Behavior: Configuration reload (planned)

  • Currently logs "Received SIGHUP, reloading configuration..."
  • TODO: Implementation pending (see daemon.rs line 25)

Daemon Components​

The daemon manages multiple background tasks:

Source: /path/to/fido-bridge/crates/client/src/daemon.rs (lines 76-280)

1. Signal Handler​

Spawned task listening for SIGTERM, SIGINT, SIGHUP (lines 82-85).

2. Embedded Server (Optional)​

If configured with mode = "embedded":

  • Starts HTTP server on configured port (default: 3000)
  • See lines 88-97

3. D-Bus Service​

Always started:

  • Registers org.fidobridge.Client on session bus
  • Object path: /org/fidobridge/Client
  • See lines 99-101

4. UHID FIDO Device​

Virtual FIDO device emulation:

  • Creates /dev/hidrawX device
  • Handles CTAP2 protocol
  • Routes to paired devices via NFC
  • See lines 104-245

5. Background Message Polling​

Polls relay server every 250ms:

  • Checks for incoming WebAuthn responses
  • Routes responses to appropriate UHID channel
  • See lines 247-261

6. D-Bus Session Cleanup​

Background task (60-second interval):

  • Cleans up expired pairing sessions
  • Emits PairingFailed signals for timeouts
  • See /path/to/fido-bridge/crates/client/src/dbus_interface.rs (lines 520-563)

Troubleshooting​

Service Won't Start​

  1. Check logs:

    fido-bridge logs

  2. Run diagnostics:

    fido-bridge diagnose

  3. Check UHID permissions:

    getfacl /dev/uhid

  4. Verify service file:

    cat ~/.config/systemd/user/fido-bridge.service

Service Crashes Immediately​

  1. Check for permission errors:

    journalctl --user -u fido-bridge -n 100 | grep -i "permission denied"

  2. Verify binary exists:

    ls -l ~/.local/bin/fido-bridge

  3. Test binary directly:

    ~/.local/bin/fido-bridge --version

D-Bus Interface Not Available​

  1. Check service is running:

    systemctl --user is-active fido-bridge

  2. Verify D-Bus registration:

    busctl --user list | grep fidobridge

  3. Check D-Bus logs:

    journalctl --user -u fido-bridge | grep -i "dbus"

High CPU Usage​

  1. Check polling interval in config:

    [timeouts]
    poll_interval_ms = 250  # Increase if needed

  2. Monitor active transactions:

    fido-bridge logs | grep -i "transaction"

  3. Restart service to clear state:

    fido-bridge restart

Advanced Usage​

Running in Foreground​

For debugging, run the daemon in foreground:

# Stop service first
systemctl --user stop fido-bridge

# Run directly
~/.local/bin/fido-bridge daemon

Press Ctrl+C to stop.

Enabling Debug Logging​

Temporary (foreground mode):

RUST_LOG=debug ~/.local/bin/fido-bridge daemon

Permanent (service mode):

  1. Edit service file:

    nano ~/.config/systemd/user/fido-bridge.service

  2. Change environment line:

    Environment="RUST_LOG=debug"

  3. Reload and restart:

    systemctl --user daemon-reload
    systemctl --user restart fido-bridge

Verbose Logging​

For maximum verbosity:

RUST_LOG=trace ~/.local/bin/fido-bridge daemon

Or add --verbose flag:

fido-bridge --verbose daemon

Source: /path/to/fido-bridge/crates/client/src/main.rs (lines 34-35, 103-107)

See Also​