Somo Deployment & Usage Guide

1. Prerequisites

Operating Systems:

• Linux (tested with Debian-based and Arch-based distributions)
• macOS (Intel and Apple Silicon)

Required Tools:

• For installation from source: Rust toolchain (cargo, rustc)
• For Debian installation: dpkg package manager
• For Arch installation: yay AUR helper or pacman
• For Homebrew installation: Homebrew package manager
• For Nix installation: Nix with Flakes support

Permissions:

• Root/sudo access is recommended to view all processes and ports
• For cargo installations: User must have write access to ~/.cargo/bin/

2. Installation

Using Cargo (Recommended)

# Install from crates.io (stable version)
cargo install somo

# Create symlink for sudo usage (optional but recommended)
sudo ln -s ~/.cargo/bin/somo /usr/local/bin/somo

# Verify installation
sudo somo --version

From GitHub (Development Version)

# Install cutting-edge development version
cargo install --git https://github.com/theopfr/somo

# Warning: May be unstable or contain incomplete features

Package Managers

Debian/Ubuntu:

1. Download the latest .deb file from releases
2. Install with: sudo dpkg -i somo_*.deb

Arch Linux:

# Using yay (AUR helper)
yay -S somo

# Or manually build from AUR

Homebrew (macOS & Linux):

brew install somo

Nix:

# Build using Nix with Flakes
nix build 'github:theopfr/somo?dir=nix'
sudo ./result/bin/somo

3. Configuration

Configuration File

Somo supports a configuration file for persistent settings:

# Generate default config file
somo generate-config-file

# View config file location
somo --config-file

# Ignore config file for a single run
somo --no-config

Environment Variables

• PROCFS_ROOT: Override the default /proc/ path (Linux only)

  PROCFS_ROOT=/custom/proc/path somo
  

Shell Completions

Generate shell completions for your preferred shell:

# Generate and install completions
somo generate-completions <shell>
# Where <shell> is: bash, zsh, fish, powershell, or elvish

4. Build & Run

Building from Source

# Clone the repository
git clone https://github.com/theopfr/somo.git
cd somo

# Build in debug mode
cargo build

# Build in release mode (optimized)
cargo build --release

# The binary will be at: ./target/release/somo

Running Somo

Basic usage:

# View all connections (requires sudo for full visibility)
sudo somo

# Alternative if symlinked
sudo /usr/local/bin/somo

Development Build

# Run directly with cargo
cargo run -- [OPTIONS]

# Example with flags
cargo run -- -t -l  # Show TCP listening connections

5. Deployment

Binary Distribution

Since Somo is a statically-linked Rust binary, deployment is straightforward:

1. Build the release binary:

   cargo build --release --target x86_64-unknown-linux-gnu
   

2. Distribute the binary:

   • Copy target/release/somo to target systems
   • Ensure executable permissions: chmod +x somo
   • Optionally move to system PATH: sudo mv somo /usr/local/bin/

Container Deployment

Create a minimal Docker container:

FROM rust:alpine AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM alpine:latest
COPY --from=builder /app/target/release/somo /usr/local/bin/somo
ENTRYPOINT ["somo"]

Platform Recommendations

• Personal/Development Use: Install via package manager (cargo, brew, apt)
• System Administration: Deploy binary to /usr/local/bin/ on all managed servers
• Containerized Environments: Include binary in monitoring containers
• CI/CD Pipelines: Install via cargo in build steps

6. Troubleshooting

Common Issues

1. "Permission denied" when running without sudo

# Solution 1: Use sudo
sudo somo

# Solution 2: Create symlink as mentioned in installation
sudo ln -s ~/.cargo/bin/somo /usr/local/bin/somo

# Solution 3: Run with CAP_NET_ADMIN capabilities (Linux)
sudo setcap cap_net_admin+ep $(which somo)

2. Missing processes or ports in output

• Ensure you're running with sufficient privileges (sudo)
• On Linux, verify /proc filesystem is accessible
• Check if process filtering is too restrictive

3. JSON output formatting issues

# Ensure proper JSON parsing
somo --json | jq .  # Pipe to jq for pretty printing

4. Homebrew installation fails on macOS

# Update Homebrew and retry
brew update
brew doctor
brew install somo

5. Arch Linux AUR build fails

# Ensure base-devel is installed
sudo pacman -S base-devel
yay -S somo --noconfirm

6. Custom format syntax errors

# Check format syntax
somo --format "PID: {{pid}}, Protocol: {{proto}}"

# Available template variables:
# {{pid}}, {{proto}}, {{local_port}}, {{remote_address}}
# {{remote_port}}, {{program}}, {{state}}

7. Process killing doesn't work

• Ensure you have permission to send signals to the target process
• Some processes may be protected (systemd, kernel processes)
• Use -k flag after viewing connections:

  sudo somo -k
  

Debug Mode

For detailed debugging, build and run with Rust debug output:

RUST_LOG=debug cargo run -- [OPTIONS]

Reporting Issues

If problems persist:

1. Check the GitHub Issues
2. Run with --version to confirm installed version
3. Provide OS and kernel version information
4. Include exact command and error output