Changes

Page history
update command-line-options.md authored by tem_invictus's avatar tem_invictus
Show whitespace changes
Inline Side-by-side
pages/setup/command-line-options.md
View page @ 0d650d41
# Command Line Options
OSCam supports various command-line parameters to configure its behavior at startup.
OSCam offers extensive command-line configuration options to customize its behavior at startup. These parameters allow you to control directories, logging, debugging, and runtime behavior without modifying configuration files.
## Usage
## Basic Usage
```
oscam [parameters]
```bash
oscam [options]
```
## Directories
## Quick Reference
| Option | Description |
|--------|-------------|
| `-c, --config-dir <dir>` | Read configuration files from `<dir>`.<br>Default: `/usr/local/etc` |
| `-t, --temp-dir <dir>` | Set temporary directory to `<dir>`.<br>Default: `/tmp/.oscam` (Linux/macOS) or OS-TMP (Cygwin) |
### Essential Options
## Startup
The most commonly used options for typical setups:
| Option | Description |
|--------|-------------|
| `-b, --daemon` | Start in the background as daemon.<br>(On STAPI/STAPI5 systems, use `-f` instead) |
| `-f, --foreground` | Start in the foreground mode.<br>(Only available on STAPI/STAPI5 systems) |
| `-B, --pidfile <pidfile>` | Create pidfile when starting. |
| `-r, --restart <level>` | Set restart level (requires WebIf):<br>• `0` - Restart disabled (exit on restart request)<br>• `1` - WebIf restart is active (default)<br>• `2` - Like 1, but also restart on segfaults |
| `-w, --wait <secs>` | Set how many seconds to wait at startup for the system clock to be set correctly.<br>Default: `60` |
```bash
# Start as background daemon with custom config
oscam -b -c /etc/oscam
## Logging
# Start with debug logging enabled
oscam -d 255
| Option | Description |
|--------|-------------|
| `-I, --syslog-ident <ident>` | Set syslog ident.<br>Default: `oscam` |
| `-S, --show-sensitive` | Do not filter sensitive info (card serials, boxids) from the logs. |
| `-d, --debug <level>` | Set debug level mask used for logging (see [Debug Levels](#debug-levels) below).<br>Default: `0` (no extra debugging) |
# Start with custom directories and pidfile
oscam -b -c /etc/oscam -t /var/tmp/oscam -B /var/run/oscam.pid
```
### Debug Levels
## Directory Configuration
Debug levels can be combined by adding their values together:
| Level | Description |
|-------|-------------|
| `0` | No extra debugging (default) |
| `1` | Detailed error messages |
| `2` | ATR parsing info, ECM, EMM and CW dumps |
| `4` | Traffic from/to the reader |
| `8` | Traffic from/to the clients |
| `16` | Traffic to the reader-device on IFD layer |
| `32` | Traffic to the reader-device on I/O layer |
| `64` | EMM logging |
| `128` | DVBAPI logging |
| `256` | Loadbalancer logging |
| `512` | CACHEEX logging |
| `1024` | Client ECM logging |
| `2048` | CSP logging |
| `4096` | CWC logging |
| `8192` | CW Cache logging (CS_CACHEEX_AIO only) |
| `65535` | Debug all |
**Example:** To enable detailed error messages (1) and ECM/EMM dumps (2), use `-d 3`
## Settings
Configure where OSCam looks for configuration files and stores temporary data.
| Option | Description |
|--------|-------------|
| `-p, --pending-ecm <num>` | Set the maximum number of pending ECM packets.<br>Default: `32`<br>Maximum: `4096` |
| Option | Description | Default |
|--------|-------------|---------|
| `-c, --config-dir <dir>` | Configuration files directory | `/usr/local/etc` |
| `-t, --temp-dir <dir>` | Temporary files directory | `/tmp/.oscam` (Linux/macOS)<br>`OS-TMP` (Cygwin) |
## Debug Parameters
**Example:**
```bash
oscam -c /etc/oscam -t /var/tmp/oscam
```
These options are intended for development and troubleshooting:
## Process Management
| Option | Description |
|--------|-------------|
| `-a, --crash-dump` | Write `oscam.crash` file on segfault. This option requires GDB to be installed and OSCam executable to contain debug information (run `oscam-XXXX.debug`). |
| `-s, --capture-segfaults` | Capture segmentation faults. |
| `-g, --gcollect <mode>` | Garbage collector debug mode:<br>• `1` - Immediate free<br>• `2` - Check for double frees |
Control how OSCam runs as a system process.
| Option | Description | Notes |
|--------|-------------|-------|
| `-b, --daemon` | Run as background daemon | Standard mode for production |
| `-f, --foreground` | Run in foreground | Only on STAPI/STAPI5 systems |
| `-B, --pidfile <file>` | Create PID file at specified path | Useful for init scripts |
| `-w, --wait <seconds>` | Wait for system clock sync at startup | Default: `60` seconds |
## Information
**Daemon vs Foreground:**
- Use `-b` (daemon) for most systems to run OSCam in the background
- Use `-f` (foreground) on STAPI/STAPI5 systems or when debugging
**Example:**
```bash
oscam -b -B /var/run/oscam.pid -w 30
```
## Restart Behavior
Configure how OSCam handles restart requests (requires WebIf module).
| Option | Description |
|--------|-------------|
| `-h, --help` | Show command line help text. |
| `-V, --build-info` | Show OSCam binary configuration and version. |
| `-r, --restart <level>` | Set restart level (see table below) |
## Examples
**Restart Levels:**
Start OSCam in daemon mode with custom config directory:
| Level | Behavior | Use Case |
|-------|----------|----------|
| `0` | Exit on restart request | Manual control only |
| `1` | WebIf restart enabled (default) | Normal operation |
| `2` | Restart on segfaults | Automatic recovery |
**Example:**
```bash
oscam -b -r 2 # Restart automatically on crashes
```
oscam -b -c /etc/oscam
## Logging Configuration
Control OSCam's logging behavior and verbosity.
### Basic Logging Options
| Option | Description | Default |
|--------|-------------|---------|
| `-I, --syslog-ident <ident>` | Syslog identifier | `oscam` |
| `-S, --show-sensitive` | Show sensitive data (serials, IDs) | Disabled (filtered) |
| `-d, --debug <level>` | Debug level mask | `0` (no debug) |
**Example:**
```bash
oscam -I oscam-server -S -d 255
```
Start OSCam with debug logging for client traffic:
### Debug Levels
Debug levels use bitmask values that can be combined by adding them together.
| Value | Component | What It Logs |
|-------|-----------|--------------|
| `0` | None | No extra debugging (default) |
| `1` | Errors | Detailed error messages |
| `2` | Cards | ATR parsing, ECM, EMM, and CW dumps |
| `4` | Reader Traffic | Communication with card readers |
| `8` | Client Traffic | Communication with clients |
| `16` | IFD Layer | Reader device traffic (IFD layer) |
| `32` | I/O Layer | Reader device traffic (I/O layer) |
| `64` | EMM | EMM processing and logging |
| `128` | DVBAPI | DVB API operations |
| `256` | Load Balancer | Load balancing decisions |
| `512` | Cache Exchange | CACHEEX operations |
| `1024` | Client ECM | Client ECM requests |
| `2048` | CSP | CSP protocol operations |
| `4096` | CWC | CWC protocol operations |
| `8192` | CW Cache | Control word caching (CS_CACHEEX_AIO) |
| `65535` | All | Enable all debug output |
**Common Debug Combinations:**
```bash
# Basic debugging (errors + card data)
oscam -d 3 # 1 + 2
# Client troubleshooting (errors + client traffic)
oscam -d 9 # 1 + 8
# Reader debugging (errors + reader traffic + IFD layer)
oscam -d 21 # 1 + 4 + 16
# Full card debugging (errors + cards + reader + IFD + I/O)
oscam -d 55 # 1 + 2 + 4 + 16 + 32
# Everything
oscam -d 65535
```
oscam -d 8
## Performance Tuning
Optimize OSCam's performance for your specific setup.
| Option | Description | Default | Maximum |
|--------|-------------|---------|---------|
| `-p, --pending-ecm <num>` | Maximum pending ECM packets | `32` | `4096` |
This setting controls the ECM queue size. Increase for high-traffic setups:
```bash
oscam -p 128 # For busy servers
```
Start OSCam with custom temp directory and pidfile:
## Development & Debugging
Advanced options for troubleshooting and development (not recommended for production).
| Option | Description | Requirements |
|--------|-------------|--------------|
| `-a, --crash-dump` | Write `oscam.crash` on segfault | GDB installed, debug binary |
| `-s, --capture-segfaults` | Capture segmentation faults | - |
| `-g, --gcollect <mode>` | Garbage collector debug mode | - |
**Garbage Collector Modes:**
- `1` - Immediate free (detect memory issues)
- `2` - Check for double frees
**Example:**
```bash
oscam -a -s -g 2 # Full crash debugging
```
oscam -t /var/tmp/oscam -B /var/run/oscam.pid
## Information & Help
Get information about OSCam without starting the server.
| Option | Description |
|--------|-------------|
| `-h, --help` | Display help text |
| `-V, --build-info` | Show build configuration and version |
**Examples:**
```bash
# Show help
oscam -h
# Check compiled modules
oscam -V
```
Show build information:
## Complete Examples
### Production Setup
```bash
# Reliable production configuration
oscam -b \
-c /etc/oscam \
-t /var/tmp/oscam \
-B /var/run/oscam.pid \
-r 2 \
-I oscam-prod
```
oscam -V
### Development & Testing
```bash
# Debug client issues
oscam -c /etc/oscam \
-d 1033 \
-S
```
Start with combined debug levels (errors + ECM dumps + client traffic):
### High-Performance Server
```bash
# Optimized for many clients
oscam -b \
-c /etc/oscam \
-p 256 \
-r 1 \
-w 30
```
oscam -d 11
### Troubleshooting
```bash
# Maximum debugging
oscam -d 65535 \
-S \
-a \
-s
```
## Notes
## Best Practices
### For Production
- Always use `-b` (daemon mode) on standard systems
- Set `-r 2` for automatic recovery from crashes
- Use `-B` with pidfile for proper init script integration
- Keep debug level at `0` unless troubleshooting
### For Testing
- Use meaningful syslog identifiers with `-I` when running multiple instances
- Enable sensitive data logging `-S` only during active troubleshooting
- Combine debug levels to focus on specific components
- Remember to disable debug logging after troubleshooting
### For Development
- Use crash dumps `-a` only with debug builds
- Monitor memory with garbage collector `-g` during testing
- Test restart behavior with `-r` levels before deployment
## Platform-Specific Notes
**STAPI/STAPI5 Systems:**
- Use `-f` (foreground) instead of `-b` (daemon)
- These platforms require foreground operation
**Embedded Devices:**
- Use lower `-w` values (10-20 seconds) if clock sync is fast
- Consider smaller `-p` values (16-32) if memory is limited
- Most options can be combined. For example: `oscam -b -c /etc/oscam -d 255`
- The `-r` restart option is only available when OSCam is compiled with WebIf support
- Debug levels are bitmasks and can be combined by adding their values
- Platform-specific: STAPI/STAPI5 systems use `-f` (foreground) instead of `-b` (daemon)
**Multi-Instance Setups:**
- Use unique `-I` identifiers for each instance
- Specify different `-t` temp directories for each instance
- Use separate `-B` pidfiles for process management
\ No newline at end of file