# Wallarm Deployment System

A comprehensive solution for deploying Wallarm filtering nodes on virtual machines or bare metal servers. This system provides automated deployment, preflight checks, and management of Wallarm security nodes with **two deployment types**: **Docker** (containerized) and **Native** (installed directly on the OS, no Docker required).

## Deployment Types

| | **Docker** | **Native** |
|---|---|---|
| Runtime | Wallarm container on Docker engine | Wallarm NGINX module installed directly on the OS |
| Artifacts | Docker static binaries + Wallarm image (from Git repo or local) | Wallarm all-in-one installer (`meganode.wallarm.com`) |
| Multi-node on one host | ✅ Yes (unique ports) | ⚠️ One node per host (single system NGINX) |
| Directory | `docker/` | `native/` |
| Requires Docker | ✅ (installed automatically) | ❌ Never installed |
| Best for | LXC/containers, multiple nodes, air-gapped | Simple single VM, minimal footprint, no containers |

## Features

- **Automated Preflight Checks** – Validates system readiness, network connectivity, and resource availability (per deployment type)
- **Smart Artifact Management** – Git Repositorys-first approach with local fallback support (Docker type)
- **Multiple Node Support (Docker)** – Deploy multiple Wallarm instances on the same VM with unique port configurations
- **Interactive Configuration** – User-friendly prompts for cloud region, ports, token, and upstream applications
- **Comprehensive Validation** – Network tests, port availability checks, and deployment verification
- **Persistence & Management** – Automatic service creation (systemd/OpenRC/SysV), start scripts, and health monitoring
- **Post‑Deployment Reconfiguration** – Easily update trusted proxy IPs and change operation mode without redeploying
- **Clean Uninstallation** – Safe removal of containers, packages, and configuration files

## Prerequisites

### System Requirements
- **Operating System**: Linux (Ubuntu 20.04+, CentOS/RHEL 8+, Debian 11+, Alpine)
- **Architecture**: x86_64 (amd64) or aarch64 (arm64) for native; x86_64 for Docker artifacts
- **Memory**: Minimum 2GB RAM (4GB recommended for production)
- **Storage**: Minimum 10GB free disk space
- **Network**: Outbound connectivity to Wallarm cloud endpoints

### Software Dependencies
- **Bash**: Version 4.0+ (included with most Linux distributions)
- **curl** or **wget**: For downloading scripts and artifacts
- **sudo**: For package installation and system configuration
- **systemd**, **OpenRC** or **sysvinit**: For service management

## Quick Start

### 1. Download the Scripts

Use the wrapper script to download all necessary tools. You will be asked to select the deployment type (`docker` or `native`):

```bash
curl -fsSL "https://git.sechpoint.app/customer-engineering/wallarm/raw/branch/main/setup.sh" | bash
```

To select non-interactively (e.g. for automation):

```bash
DEPLOYMENT_TYPE=native curl -fsSL "https://git.sechpoint.app/customer-engineering/wallarm/raw/branch/main/setup.sh" | bash
```

The setup script downloads the shared library and makes executable:

- `common/wallarm-lib.sh` – Shared functions for both deployment types
- `docker/wallarm-ct-check.sh` – Preflight validation (Docker)
- `docker/wallarm-ct-deploy.sh` – Main deployment script (Docker)
- `docker/wallarm-ct-reconfigure.sh` – Modify configuration after deployment (Docker)
- `docker/wallarm-ct-uninstall.sh` – Remove a Wallarm node (Docker)
- `native/wallarm-ct-check.sh` – Preflight validation (Native)
- `native/wallarm-ct-deploy.sh` – Main deployment script (Native)
- `native/wallarm-ct-reconfigure.sh` – Modify configuration after deployment (Native)
- `native/wallarm-ct-uninstall.sh` – Remove a Wallarm node (Native)
- `native/wallarm-native.sh` – Unified single-script manager for the Wallarm Native Node (connector mode)

### 2. Run Preflight Check

```bash
# Docker deployment
./docker/wallarm-ct-check.sh

# Native deployment
./native/wallarm-ct-check.sh
```

The preflight check will:
- Verify system compatibility (OS, architecture, init system)
- Test network connectivity to Wallarm cloud endpoints
- Validate artifact availability (Docker: Git repo / local files; Native: all-in-one installer)
- Validate resource availability
- Generate a `.env` file with results

### 3. Deploy Wallarm Node

```bash
# Docker deployment
sudo ./docker/wallarm-ct-deploy.sh

# Native deployment
sudo ./native/wallarm-ct-deploy.sh
```

The deployment script will:
1. Read preflight check results
2. Prompt for configuration (ports, upstream application, Wallarm token, trusted proxies)
3. **Docker**: Install Docker, download and load the Wallarm image, configure and start the container
4. **Native**: Download and run the Wallarm all-in-one installer, configure NGINX, reload and verify
5. Verify deployment with health checks

## Required Information Before Deployment

To ensure a smooth deployment, have the following information ready before starting the script:

| Item | Description | Example | Notes |
|------|-------------|---------|-------|
| **Inbound Port** | The port on which the Wallarm node will listen for incoming HTTP traffic. | `80` (HTTP) or `8080` | Must be unused on the server. If port 80 is already in use, choose another. |
| **Application Server (Upstream) IP/Hostname** | The IP address or hostname of the backend application that Wallarm will forward traffic to. | `192.168.1.100` or `app.internal.local` | Must be reachable from the Wallarm node. If the application runs on the same physical machine, do **not** use `127.0.0.1` – use the host's actual IP. |
| **Application Server Port** | The port on which the backend application listens. | `8080` | Must be open and listening. |
| **Wallarm Node Token** | A token obtained from the Wallarm Console when creating a new "Wallarm node". | `base64_encoded_string` | Copy it exactly. It will be pasted during the deployment process. |
| **Trusted Proxy IPs/CIDRs** (Optional) | The IP address(es) of any load balancers, firewalls, or CDNs that sit in front of the Wallarm node and set the `X-Real-IP` header. | `10.0.0.10` or `192.168.0.0/24` | If the node is directly accessible from the internet (no proxy in front), leave empty. Multiple entries can be space-separated. |
| **Wallarm Cloud Region** | Which Wallarm cloud to use – US or EU. | `US` or `EU` | The script will test connectivity to both and only show reachable ones. |
| **Operation Mode** (Optional, can be changed later) | The initial operation mode. `monitoring` only logs attacks, `block` actively blocks. | `monitoring` (recommended for first deployment) | The script defaults to `monitoring`. You can change it later using the reconfigure script. |

### Additional Preparation Steps

- **Ensure the backend application is running** and reachable from the Wallarm server. Test with `telnet <upstream_ip> <upstream_port>`.
- **If you plan to use a custom domain**, be prepared to configure DNS to point to the server's public IP (or the load balancer) – the Wallarm node itself does not require a domain for basic setup.
- **If the server is behind a firewall**, open the inbound port (e.g., 80) to allow traffic from the internet or the load balancer.

## Detailed Usage

### Workflow Overview

1. **Preflight Check** → **Deployment** → **Verification** → **Management**

### Configuration Requirements

#### Wallarm Node Token
Before deployment, you need a Wallarm Node Token from the Wallarm Console:
- **Create Token**: Navigate to Wallarm Console → **Nodes** → **Create node**
- **Token Format**: Base64 encoded string (alphanumeric with `+`, `/`, `=`, `-`, `_`)
- **Documentation**: [Official Wallarm Documentation](https://docs.wallarm.com/)

#### Header Configuration for Firewalls/Ingress Controllers
To ensure proper IP address detection and metadata forwarding, configure your firewall or ingress controller to include these headers:

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
```

**Note**: The deployment scripts configure the first three headers automatically. You must manually add `X-Forwarded-Host: "$host"` to your existing firewall/ingress configuration.

## Docker Deployment (`docker/`)

### Multiple Node Deployment on Same VM

You can deploy multiple Wallarm nodes on the same virtual machine by:

1. **Unique Port Configuration**: Each instance must use unique ingress and monitoring ports
   - Default ingress port: 80 (configurable during deployment)
   - Monitoring port: ingress_port + 10 (auto-calculated)
   - Example: Instance 1 (80/90), Instance 2 (8080/8090), Instance 3 (8888/8898)

2. **Instance Naming**: Each deployment generates a unique instance name
   - Format: `wallarm-<hostname>-<date>-<random>`
   - Example: `wallarm-server1-20250324-ab3c`

3. **Isolated Configuration**: Each instance has its own:
   - Docker container with unique name
   - Configuration directory (`/opt/wallarm-<instance-name>/`)
   - Port binding and network namespace
   - Log files and start scripts

**Resource Considerations for Multiple Nodes**:
- Add 500MB RAM per additional Wallarm instance
- Each instance requires ~2GB disk space
- Consider CPU allocation (1 vCPU core per 2-3 instances for moderate traffic)

## Native Deployment (`native/`)

The native deployment installs Wallarm directly on the operating system **without Docker**, using the official Wallarm **all-in-one installer**:

- The installer is downloaded from `https://meganode.wallarm.com/` (version configurable via the `WALLARM_VERSION` environment variable, default `6.12.7`)
- It automatically detects your OS and NGINX version, adds the Wallarm repositories, installs `wallarm-node` + the NGINX dynamic module, and registers the node
- Node registration is performed by the installer itself in batch mode (using your Wallarm token)
- The node configuration is written to `/opt/wallarm/etc/wallarm/node.yaml`
- The system NGINX is configured with a `wallarm-<instance>.conf` server block in `/etc/nginx/conf.d/`

**Notes on native deployment:**
- **One node per host**: native uses the system NGINX, so multiple Wallarm nodes on one host are not supported (unlike Docker). Use unique ingress ports only if you run a single node alongside other services.
- The deploy script keeps a copy of the generated NGINX config in `/opt/wallarm/<instance-name>/nginx.conf` and a log of the `nginx -t` test.
- `curl http://127.0.0.8/wallarm-status` reports Wallarm module statistics after deployment.

### Example: Version Pinning

```bash
WALLARM_VERSION=6.12.7 sudo ./native/wallarm-ct-deploy.sh
```

### Unified Node Manager (`native/wallarm-native.sh`)

For the **Wallarm Native Node** product (go-node, `connector-server` mode, no NGINX module), the repository provides a unified single-script manager. It manages multiple isolated nodes under `/opt/wallarm/nodes/` via a systemd template unit (`wallarm-node@<name>.service`):

```bash
sudo ./native/wallarm-native.sh --preflight     # preflight checks only
sudo ./native/wallarm-native.sh --install       # interactive multi-node install (parallel)
sudo ./native/wallarm-native.sh --config --node node1 --address 0.0.0.0:9090
sudo ./native/wallarm-native.sh --remove --node node2
sudo ./native/wallarm-native.sh --status [NODE] # node status (all or one)
```

Key characteristics:
- **Preflight checks** run automatically before `--install` and are available standalone via `--preflight` (root, systemd, architecture, required commands, installer + Wallarm cloud connectivity, disk/memory, listen-port availability)
- Per-node isolated directories (`etc/`, `var/log/`, `var/run/`), with the Wallarm token stored in a `chmod 600` env file
- All-in-one installer is downloaded from `https://repo.wallarm.com/linux/wallarm-native-node/latest/all-in-one/` (override with `WALLARM_INSTALLER_URL`, architecture with `WALLARM_INSTALLER_ARCH`)
- Parallel installation with per-node install logs (`install.log`)

> **Note:** This script targets the Wallarm **Native Node** (connector mode). The `native/wallarm-ct-*.sh` scripts target the **NGINX-module** native deployment. Both are no-Docker options; choose the one that matches your Wallarm product.

## Reconfiguration Script (`wallarm-ct-reconfigure.sh`)

After deployment, you may need to adjust:

- **Trusted proxy IPs/CIDRs** – When the network topology changes (new load balancer, CDN, firewall)
- **Operation mode** – Switch from `monitoring` to `block` after verifying correct operation

The reconfigure script safely modifies the configuration of an existing instance, creates a backup, and applies the changes (Docker: restarts the container; Native: tests and reloads NGINX).

**Usage**:
```bash
# Docker
sudo ./docker/wallarm-ct-reconfigure.sh

# Native
sudo ./native/wallarm-ct-reconfigure.sh
```

It will detect installed instances, show current settings, and guide you through the changes.

## Uninstallation (`wallarm-ct-uninstall.sh`)

To completely remove a Wallarm node:

```bash
# Docker: remove container/image and optionally Docker
sudo ./docker/wallarm-ct-uninstall.sh

# Native: remove NGINX config, Wallarm packages, and node data
sudo ./native/wallarm-ct-uninstall.sh
```

## Artifact Sources

### Docker Deployment (Priority Order)

The Docker deployment uses a smart fallback approach for artifact retrieval:

1. **Primary Source**: Git Repositorys
   - URL: `https://git.sechpoint.app/customer-engineering/wallarm`
   - Contains: `docker/binaries/` (Docker static binaries) and `docker/images/` (Wallarm images) with SHA256 checksums
   - Benefits: Version control, access control, audit trail

2. **Secondary Source**: Local Directories
   - `docker/binaries/` – Docker static binaries (`docker-29.2.1.tgz`)
   - `docker/images/` – Wallarm Docker images (`wallarm-node-6.11.0-rc1.tar.gz`)
   - Benefits: Air‑gapped environments, faster deployment

3. **Tertiary Source**: Current Directory
   - Any `docker-*.tgz` or `wallarm-node-*.tar.gz` files in script location
   - Benefits: Ad‑hoc deployments, testing scenarios

### Native Deployment (Source)

The native deployment downloads the Wallarm **all-in-one installer** directly from `https://meganode.wallarm.com/`. No Docker artifacts are required. Current versions are listed at [node-artifact-versions](https://docs.wallarm.com/updating-migrating/node-artifact-versions/).

## Suggested Resources

### Hardware Recommendations

| Deployment Type | vCPUs | RAM  | Storage | Network | Recommended For |
|----------------|-------|------|---------|---------|-----------------|
| **Development** | 2     | 4GB  | 20GB    | 100Mbps | Testing, PoC environments |
| **Production**  | 4     | 8GB  | 40GB    | 1Gbps   | Moderate traffic (up to 100 RPS) |
| **Enterprise**  | 8+    | 16GB+| 100GB   | 10Gbps  | High traffic, multiple nodes |

### Cloud VM Recommendations
- **AWS**: t3.large (development), m5.xlarge (production), c5.2xlarge (enterprise)
- **Azure**: D2s v3 (development), D4s v3 (production), D8s v3 (enterprise)
- **GCP**: e2-standard-4 (development), n2-standard-8 (production), c2-standard-8 (enterprise)

### Bare Metal Considerations
- **CPU**: Intel Xeon Silver/Gold or AMD EPYC (minimum 4 physical cores)
- **Memory**: ECC RAM recommended for production environments
- **Storage**: SSD/NVMe for better I/O performance
- **Network**: Dual NIC for redundancy, 10Gbps recommended

## Script Reference

### `common/wallarm-lib.sh`
**Purpose**: Shared library used by all deployment scripts (both types)

**Key Functions**:
- Logging (`log_message`, `fail_with_remediation`)
- System detection (OS, architecture, init system)
- Network connectivity tests
- Preflight `.env` parsing (`load_env_file`)
- Cloud region selection (`select_cloud_region`)
- Validation helpers (IP address, CIDR, port availability)
- Artifact download and checksum verification

### `docker/wallarm-ct-check.sh` / `native/wallarm-ct-check.sh`
**Purpose**: System validation and preflight checks

**Key Functions**:
- OS compatibility verification (Ubuntu, CentOS, Debian, Alpine)
- Network connectivity testing (US/EU cloud endpoints)
- Resource availability assessment
- Artifact source validation (Docker: binaries/images; Native: installer)
- Environment file generation (`.env`)

**Usage**:
```bash
# Run check with default settings
./<type>/wallarm-ct-check.sh

# Enable debug output
DEBUG=1 ./<type>/wallarm-ct-check.sh

# Disable SSL certificate validation (for self-signed certs)
WALLARM_INSECURE_SSL=0 ./<type>/wallarm-ct-check.sh
```

### `docker/wallarm-ct-deploy.sh`
**Purpose**: Wallarm node deployment and configuration (Docker)

**Key Functions**:
- Interactive configuration wizard
- Docker engine installation (with VFS storage driver for LXC)
- Artifact download with checksum verification
- Wallarm container deployment
- Nginx configuration with proper headers
- Health check and deployment verification

**Usage**:
```bash
# Interactive deployment
sudo ./docker/wallarm-ct-deploy.sh

# Deployment with pre-filled environment (optional)
WALLARM_TOKEN="your_token_here" sudo ./docker/wallarm-ct-deploy.sh
```

### `native/wallarm-ct-deploy.sh`
**Purpose**: Wallarm node deployment and configuration (Native, no Docker)

**Key Functions**:
- Interactive configuration wizard
- Downloads and runs the Wallarm all-in-one installer (batch mode)
- Node registration with your Wallarm token
- NGINX server block configuration (proxy, wallarm_mode, trusted proxies, health endpoint)
- NGINX test + reload
- Health check and deployment verification

**Usage**:
```bash
# Interactive deployment
sudo ./native/wallarm-ct-deploy.sh

# Pin a specific Wallarm version
WALLARM_VERSION=6.12.7 sudo ./native/wallarm-ct-deploy.sh

# Add node labels (group)
WALLARM_LABELS='group=prod' sudo ./native/wallarm-ct-deploy.sh
```

### `native/wallarm-native.sh`
**Purpose**: Unified single-script manager for the Wallarm Native Node (connector mode, no Docker/NGINX module)

**Key Functions**:
- Preflight checks (root, systemd, architecture, commands, connectivity, resources, ports)
- Interactive multi-node installation in parallel with per-node systemd template units
- Configuration updates (address, token, labels) and node removal
- Status reporting via systemd

**Usage**:
```bash
# Preflight only
sudo ./native/wallarm-native.sh --preflight

# Interactive install
sudo ./native/wallarm-native.sh --install

# Update config / remove / status
sudo ./native/wallarm-native.sh --config --node node1 --address 0.0.0.0:9090
sudo ./native/wallarm-native.sh --remove --node node2
sudo ./native/wallarm-native.sh --status
```

### `wallarm-ct-reconfigure.sh`
**Purpose**: Modify configuration of an existing Wallarm node

**Key Functions**:
- Update `set_real_ip_from` (trusted proxy IPs/CIDRs)
- Change `wallarm_mode` (monitoring/block)
- Create backup of current configuration
- Apply changes (Docker: container restart; Native: NGINX reload)

**Usage**:
```bash
sudo ./<type>/wallarm-ct-reconfigure.sh
```

### `wallarm-ct-uninstall.sh`
**Purpose**: Safe removal of Wallarm nodes

**Key Functions**:
- Interactive confirmation with safety checks
- Docker: container/image removal, Docker cleanup; Native: NGINX config + package removal
- Configuration directory removal
- Optional artifact cleanup

**Usage**:
```bash
# Interactive uninstallation
sudo ./<type>/wallarm-ct-uninstall.sh
```

## Troubleshooting

### Common Issues

#### 1. Preflight Check Fails
```bash
# Check detailed errors
cat .env

# Verify network connectivity manually
curl -I https://api.wallarm.com
curl -I https://us1.api.wallarm.com

# Check system compatibility
uname -m
cat /etc/os-release
```

#### 2. Deployment Fails – Port Conflicts
```bash
# Check for listening ports
sudo ss -tlnp | grep ':80\|:8080'

# Find process using port
sudo lsof -i :80

# Configure different ports during deployment
```

#### 3. Wallarm Token Issues
```bash
# Verify token format (should be base64)
echo "your_token" | base64 -d 2>/dev/null | base64

# Get new token from Wallarm Console
# https://docs.wallarm.com/
```

#### 4. Docker Installation Problems
```bash
# Check Docker service status
sudo systemctl status docker

# Verify Docker group membership
groups $USER

# Test Docker without sudo
docker run --rm hello-world
```

#### 5. Native Installer Fails
```bash
# The all-in-one installer logs its output to the terminal and to files
# Check the current version at https://docs.wallarm.com/updating-migrating/node-artifact-versions/

# Verify node registration
ls -la /opt/wallarm/etc/wallarm/node.yaml

# Check Wallarm module status
curl http://127.0.0.8/wallarm-status
```

#### 6. Header Configuration Warnings
Ensure your upstream firewall/load balancer includes:
- `X-Real-IP: "$remote_addr"`
- `X-Forwarded-For: "$proxy_add_x_forwarded_for"`
- `X-Forwarded-Proto: "$scheme"`
- `X-Forwarded-Host: "$host"`

### Log Files
- **Preflight Check**: `~/logs/wallarm-check.log` (Docker) / `~/logs/wallarm-check-native.log` (Native)
- **Deployment**: `~/logs/wallarm-deployment.log` (Docker) / `~/logs/wallarm-deployment-native.log` (Native)
- **Docker Container Logs**: `/opt/wallarm-<instance-name>/container.log`
- **NGINX Logs (Native)**: `/var/log/nginx/error.log`
- **System Logs**: `/var/log/syslog` or `/var/log/messages`

## Security Considerations

### Network Security
- Use firewall rules to restrict access to monitoring endpoints
- Consider VPN or private networking for management interfaces
- Implement rate limiting for ingress ports

### Access Control
- Restrict `sudo` access to deployment scripts
- Use separate service accounts for Wallarm services
- Implement proper secret management for Wallarm tokens

### Monitoring & Auditing
- Enable logging with rotation
- Monitor resource usage
- Regular security updates for Docker/NGINX and host OS

## Maintenance

### Regular Tasks
1. **Log Rotation**: Configure logrotate for logs
2. **Updates**: Periodically update Docker engine/NGINX and Wallarm node
3. **Image/Version Updates**: Check for new Wallarm node versions
4. **Backup**: Regular backup of configuration directories

### Version Updates
When updating Wallarm node version:
1. **Docker**: Pull new image from Git Repositorys or official registry, stop existing container, deploy new container with updated image, verify functionality before removing old container
2. **Native**: Set `WALLARM_VERSION` to the new version and re-run the deploy script, or follow the [official upgrade guide](https://docs.wallarm.com/updating-migrating/)

## Repository Structure

```
wallarm/
├── README.md
├── changelog.md
├── setup.sh                     # Downloads scripts for a chosen deployment type
├── common/
│   └── wallarm-lib.sh           # Shared library (both deployment types)
├── docker/                      # Docker deployment
│   ├── wallarm-ct-check.sh
│   ├── wallarm-ct-deploy.sh
│   ├── wallarm-ct-reconfigure.sh
│   ├── wallarm-ct-uninstall.sh
│   ├── binaries/                # Docker static binaries
│   └── images/                  # Wallarm Docker images
└── native/                      # Native deployment (no Docker)
    ├── wallarm-ct-check.sh
    ├── wallarm-ct-deploy.sh
    ├── wallarm-ct-reconfigure.sh
    ├── wallarm-ct-uninstall.sh
    └── wallarm-native.sh        # Unified single-script node manager (Native Node product)
```

## Disclaimer

**IMPORTANT LEGAL NOTICE**

This software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall Sechpoint or its affiliates be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

### No Responsibility Clause
- Sechpoint assumes no responsibility for any harm, damage, or loss caused by the use of this software
- Users are solely responsible for testing, validating, and securing their deployments
- This software may contain bugs, security vulnerabilities, or compatibility issues
- Use at your own risk and with appropriate professional oversight

### User Responsibilities
1. **Testing**: Thoroughly test in non-production environments before deployment
2. **Security**: Implement appropriate security controls and monitoring
3. **Backup**: Maintain regular backups of configurations and data
4. **Updates**: Keep the software and dependencies updated
5. **Compliance**: Ensure usage complies with all applicable laws and regulations

### Support
- This is an unsupported deployment tool
- No official support, maintenance, or updates are guaranteed
- Community contributions are welcome via the Git repository

## Contributing

Contributions to improve the Wallarm deployment system are welcome:

1. Fork the repository on Git
2. Create a feature branch
3. Make changes with comprehensive testing
4. Submit a merge request with description

## License

Proprietary – See disclaimer section for usage terms.

## Contact & Support

- **Repository**: https://git.sechpoint.app/customer-engineering/wallarm
- **Issues**: Use the issue tracker for bug reports
- **Documentation**: [Wallarm Official Documentation](https://docs.wallarm.com/)