Skip to content
BranchesTags

Repository files navigation

Simple RSync Daemon (simple-rsyncd)

A lightweight rsync-style daemon in C++ for modern server environments.

Release status: v0.3.1 Beta — Installers and core file operations are tested (ctest 5/5 suites). This is not a drop-in replacement for native rsyncd; TLS, Prometheus, OAuth2, and full rsync(1) wire compatibility are planned for later releases. See project/PRODUCTION_GATE.md.

🚀 Features

Implemented (v0.3.1)

  • Multi-platform packaging: Linux (DEB/RPM), FreeBSD (PKG), macOS (PKG/DMG)
  • Module system: Path isolation, read-only/list/delete/overwrite permissions, include/exclude patterns
  • File operations: Upload, download, delete, directory list/create/delete with path traversal protection
  • Custom protocol: LIST / GET / PUT / DELETE / STAT with key=value arguments
  • Authentication: Password file auth with SHA-256 hashing, allow/deny user lists
  • Configuration: INI format (JSON/YAML parsers present; verify your format before relying on it)
  • Logging: Structured logging with rotation support
  • Tests: Google Test unit and integration suites (all passing)

Planned (not yet production-ready)

  • SSL/TLS encryption — interface exists; handshake not fully implemented
  • OAuth2, Prometheus, rate limiting enforcement — config stubs only
  • Native rsync client compatibility — use the custom protocol or bundled test client for now
  • YAML hot-reload — partial; treat as experimental

📋 Requirements

  • C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
  • CMake 3.16+
  • OpenSSL 1.1.1+
  • jsoncpp (for JSON configuration parsing)
  • yaml-cpp (optional, for YAML configuration parsing)
  • Linux: glibc 2.17+, pthread, rt
  • macOS: macOS 12.0+ (Monterey)
  • Windows: Windows 10+ with Visual Studio 2017+

🛠️ Installation

Quick Start

# Clone the repository
git clone https://github.com/simple-rsyncd/simple-rsyncd.git
cd simple-rsyncd
# Build the project
mkdir build &&cd build
cmake ..
make -j$(nproc)# Install
sudo make install

Dependencies

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential cmake libssl-dev libjsoncpp-dev libyaml-cpp-dev

CentOS/RHEL/Fedora

sudo yum install -y gcc-c++ cmake openssl-devel jsoncpp-devel yaml-cpp-devel
# or for newer versions:
sudo dnf install -y gcc-c++ cmake openssl-devel jsoncpp-devel yaml-cpp-devel

macOS

brew install openssl jsoncpp yaml-cpp cmake
# If you encounter permission issues during installation, run:
./scripts/fix-macos-permissions.sh

Windows

  • Install Visual Studio 2017+ with C++ support
  • Install CMake and OpenSSL
  • Use vcpkg for jsoncpp: vcpkg install jsoncpp

🚀 Usage

Basic Commands

# Start the daemon
simple-rsyncd start --config /etc/simple-rsyncd/rsyncd.conf
# Start as daemon
simple-rsyncd start --daemon --config /etc/simple-rsyncd/rsyncd.conf
# Check status
simple-rsyncd status
# Test configuration
simple-rsyncd test --config /etc/simple-rsyncd/rsyncd.conf
# Reload configuration
simple-rsyncd reload
# Stop daemon
simple-rsyncd stop
# Restart daemon
simple-rsyncd restart

Configuration

The daemon uses a hierarchical configuration system with support for:

  • Global settings: Network, SSL, authentication, logging
  • Module definitions: Path-based access control and permissions
  • Configuration formats: INI, JSON, and YAML (v0.3.0)
  • Environment variables: Variable substitution in config files (v0.3.0)
  • Hot-reloading: Automatic configuration reload on file changes (v0.3.0)
  • Configuration validation: Comprehensive validation with detailed errors

Example configurations:

INI Format:

[global]bind_address = 0.0.0.0
bind_port = 873
ssl_enabled = true
auth_enabled = true
[module:backup]path = /var/backup
comment = Backup storage
read_only = false
list = true
delete = true
overwrite = true

YAML Format:

global:
bind_address: 0.0.0.0bind_port: 873ssl:
enabled: trueauth:
enabled: truemodules:
backup:
path: /var/backupcomment: Backup storageread_only: falselist: trueallow_delete: trueoverwrite: true

JSON Format:

{
"global": {
"bind_address": "0.0.0.0",
"bind_port": 873
},
"ssl": {
"enabled": true
},
"auth": {
"enabled": true
},
"modules": {
"backup": {
"path": "/var/backup",
"comment": "Backup storage",
"read_only": false,
"list": true,
"allow_delete": true,
"overwrite": true
}
}
}

Client Usage

simple-rsyncd uses a simplified custom protocol (not full native rsync wire format). For beta testing, use the daemon’s protocol commands or the project test client.

# Example protocol commands (over TCP to bind_port, default 873)# LIST <module> <path> [key=value ...]# GET <module> <path># PUT <module> <path># DELETE <module> <path> [recursive=true]# List available modules (after connecting and authenticating if enabled)# See docs/ and src/tests/ for worked examples.

Native rsync rsync://… compatibility is not guaranteed in v0.3.1; see the v0.5.0 client matrix in project/PRODUCTION_GATE.md.

🏗️ Architecture

Core Components

  • RSyncDaemon: Main server class managing connections and modules
  • Configuration: Hierarchical configuration management with validation
  • Module: Abstract interface for file system operations
  • RSyncSession: Individual client connection handling
  • SSLContext: SSL/TLS encryption management
  • Logger: Comprehensive logging system

Module System

Modules provide:

  • Path isolation: Each module has its own root directory
  • Permission control: Read-only, list, delete, and overwrite permissions
  • Pattern filtering: Include/exclude patterns for files
  • Script hooks: Pre/post transfer, delete, and list scripts
  • Environment variables: Custom configuration per module

Security Features

  • SSL/TLS encryption: Secure file transfers
  • Authentication: Multiple authentication methods
  • Access control: IP and network restrictions
  • Path validation: Prevention of directory traversal attacks
  • Privilege dropping: Running with minimal permissions
  • Chroot support: File system isolation

🔧 Configuration

Configuration Files

  • Main config: /etc/simple-rsyncd/rsyncd.conf
  • Module configs: /etc/simple-rsyncd/modules.d/
  • User database: /etc/simple-rsyncd/users
  • SSL certificates: /etc/simple-rsyncd/ssl/

Environment Variables

# Override configuration file locationexport SIMPLE_RSYNCD_CONFIG=/path/to/config
# Enable debug modeexport SIMPLE_RSYNCD_DEBUG=1
# Set log levelexport SIMPLE_RSYNCD_LOG_LEVEL=debug

Configuration Inheritance

# Base configuration[global]ssl_enabled = true
auth_enabled = true
# Production override[global:production]ssl_enabled = true
auth_enabled = true
ssl_require_client_cert = true
# Development override[global:development]ssl_enabled = false
auth_enabled = false

📊 Monitoring

Metrics

  • Connection statistics: Active connections, total connections
  • Transfer statistics: Bytes transferred, files transferred
  • Performance metrics: Transfer rates, response times
  • Error rates: Failed transfers, authentication failures

Health Checks

  • Service health: Daemon status and responsiveness
  • Module health: Module availability and permissions
  • Resource usage: Memory, CPU, and disk usage
  • SSL certificate: Certificate expiration and validity

Prometheus Integration

# prometheus.ymlscrape_configs:
- job_name: 'simple-rsyncd'static_configs:
- targets: ['localhost:9090']metrics_path: '/metrics'

🔒 Security

SSL/TLS Configuration

[global]ssl_enabled = true
ssl_certificate_file = /etc/simple-rsyncd/ssl/server.crt
ssl_private_key_file = /etc/simple-rsyncd/ssl/server.key
ssl_ca_file = /etc/simple-rsyncd/ssl/ca.crt
ssl_cipher_suite = ECDHE-RSA-AES256-GCM-SHA384
ssl_tls_version = 1.2

Authentication (v0.3.0 Enhanced)

[global]auth_enabled = true
auth_method = password
auth_password_file = /etc/simple-rsyncd/users
auth_realm = simple-rsyncd
# Password policies (v0.3.0)password_policy_min_length = 8
password_policy_require_uppercase = true
password_policy_require_lowercase = true
password_policy_require_digits = true
password_policy_expiration_hours = 2160 # 90 days# Session management (v0.3.0)session_timeout = 3600
enable_session_management = true

Password Security:

  • Passwords are automatically hashed using SHA-256 with salt
  • Supports both plain text (backward compatible) and pre-hashed passwords
  • Password policies enforce complexity requirements
  • Password expiration and account lockout support
  • User database with CRUD operations

Access Control

[global]access_enabled = true
access_allowed_hosts = 127.0.0.1, 192.168.1.0/24
access_allowed_networks = 10.0.0.0/8
access_denied_hosts = 192.168.1.100

🚀 Performance

Optimization Features

  • Connection pooling: Efficient connection management
  • Buffer optimization: Configurable buffer sizes
  • Compression: Built-in compression support
  • Pipelining: Parallel transfer operations
  • Checksum verification: Fast file integrity checking

Benchmarking

# Test transfer performance
rsync -avz --progress /large/directory/ rsync://server/module/
# Test concurrent connectionsforiin {1..10};do
rsync -avz /test/dir/ rsync://server/module/ &donewait

🐳 Docker Support

Quick Start

# Build image
docker build -t simple-rsyncd .# Run container
docker run -d \
--name simple-rsyncd \
-p 873:873 \
-v /path/to/config:/etc/simple-rsyncd \
-v /path/to/data:/var/lib/simple-rsyncd \
simple-rsyncd

Docker Compose

version: '3.8'services:
simple-rsyncd:
build: .ports:
- "873:873"volumes:
- ./config:/etc/simple-rsyncd
- ./data:/var/lib/simple-rsyncdenvironment:
- SIMPLE_RSYNCD_CONFIG=/etc/simple-rsyncd/rsyncd.conf

🔧 Development

Building from Source

# Clone repository
git clone https://github.com/simple-rsyncd/simple-rsyncd.git
cd simple-rsyncd
# Create build directory
mkdir build &&cd build
# Configure with CMake
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_TESTS=ON \
-DBUILD_EXAMPLES=ON
# Build
make -j$(nproc)# Run tests
make test# Install
sudo make install

Development Dependencies

# Ubuntu/Debian
sudo apt-get install -y \
build-essential cmake \
libssl-dev libjsoncpp-dev \
clang-format cppcheck \
valgrind gdb
# macOS
brew install \
cmake openssl jsoncpp \
clang-format cppcheck \
valgrind lldb

Code Style

  • C++17 standard
  • Clang-format for code formatting
  • Cppcheck for static analysis
  • Valgrind for memory checking
  • Google Test for unit testing

📚 Documentation

📖 Start with the Installation Guide for first-time setup

🆕 v0.3.0 Features:

  • Password hashing and policies
  • User database and session management
  • Configuration hot-reload
  • Environment variable substitution
  • Enhanced logging with rotation
  • Comprehensive error handling

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Fork and clone
git clone https://github.com/your-username/simple-rsyncd.git
cd simple-rsyncd
# Create feature branch
git checkout -b feature/amazing-feature
# Make changes and test
make test# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature
# Create pull request

📄 License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

  • rsync project for the protocol specification
  • OpenSSL project for cryptographic libraries
  • jsoncpp project for JSON parsing
  • CMake project for build system
  • All contributors who have helped improve this project

📞 Support

🔄 Changelog

See CHANGELOG.md for a complete list of changes.

Simple RSync Daemon - Secure, fast, and reliable file synchronization for modern servers.

About

Simple Rsync Daemon [simple-rsyncd]

Topics

remote-backupremote-syncremote-sync-daemonremote-syncingrsyncrsync-backuprsync-daemon

Resources

Readme
License
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages