4. Configuration¶

This document describes how to configure the VPL-Jail-System. For more details about VPL, visit the VPL home page or the VPL plugin page at Moodle.

4.1. Changing configuration¶

The configuration is performed by editing the text file /etc/vpl/vpl-jail-system.conf. To apply the new configuration value you must restart the service (as user root).

Using systemd

systemctl restart vpl-jail-system

or using system V

service vpl-jail-system restart

4.2. Configuration file format¶

The configuration file is in text format. Each line can be empty, be a comment, or a parameter line. A comment line starts with a ‘#’ (numeric symbol). A parameter line starts with a parameter name, a ‘=’ (equals symbol), and the parameter value. Format PARAMETER=VALUE.

Warning

Beware that no space is allowed before or after the equals symbol “=”.

Example:

# This is a comment line
PARAMETER=value

4.3. Setting parameters using environment variables¶

New in version 4.0.0.

Configuration parameters can be set using environment variables, which will override settings in the configuration file. To use this feature, prefix the environment variables with VPL_JAIL_, corresponding to the parameter names you wish to set.

For example, to set the server PORT and JAILPATH, you can use the following commands in a bash shell:

export VPL_JAIL_PORT=8000
# Sets the PORT parameter to 8000
export VPL_JAIL_JAILPATH=/
# Sets the JAILPATH parameter to the root directory

Warning

When using Docker, it’s important to understand how environment variables are managed within containers. Environment variables set in Docker can be overridden by Dockerfile instructions or command-line arguments.

4.4. Network parameters¶

4.4.1. PORT¶

Socket port number to listen for http and ws connections (no ciphers). The default value is 80. The value 0 indicates no use of unciphered connections.

Example:

PORT=8080

Warning

For security reasons, current browsers do not accept WebSocket connections to ports without encryption.

4.4.2. SECURE_PORT¶

Socket port number to listen for https and wss connections. Default value 443. The value 0 indicates no use of ciphered connections. Notice that the files with the server public certificate and secret key must exist and have proper content. Example:

SECURE_PORT=4430

If this option changes, the URL of the execution server used at Moodle must be update. URL format https://yourservername:SECURE_PORT/URLPATH.

4.4.3. INTERFACE¶

Sets the network interface that the server will use. Use this parameter when your server has multiple IPs and you want to control which to use. The default value is empty, meaning the use of all network interfaces in the system.

INTERFACE=128.1.1.1

4.4.4. SSL_CIPHER_LIST¶

New in version 2.6.0.

This parameter specifies ciphers for TLS version lower than v1.3. In case of wanting to have Forward Secrecy, the value must be ECDHE. The default value is SSL_CIPHER_LIST=

Example:

SSL_CIPHER_LIST=ECDHE

4.4.5. SSL_CIPHER_SUITES¶

New in version 3.0.0.

This parameter specifies ciphers for TLSv1.3. The parameter is a colon (“:”) separated list of TLSv1.3 ciphers names in order of preference. The default value is SSL_CIPHER_SUITES=

Example:

SSL_CIPHER_SUITES=ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384

4.4.6. HSTS_MAX_AGE¶

New in version 3.0.0.

This parameter allows HTTP Strict-Transport-Security by setting the max-age parameter of the Strict-Transport-Security HTTP header. This parameter requires not accepting non-ciphered requests, then you must also use PORT = 0. With the proper ciphers and this feature activated you will get A+ in the server check of the SSL Labs.

Example:

HSTS_MAX_AGE=31536000

4.4.7. SSL_CERT_FILE¶

New in version 2.6.0.

Indicates the path to the server’s certificate in PEM format. If your Certification Authority is not a root authority you may need to add the chain of certificates of the intermediate CAs to this file. The default value is SSL_CERT_FILE=/etc/vpl/cert.pem From version 4.0.0, certificates can be updated without restarting the service. The file is checked every 5 minutes for modifications, and certificates are updated if necessary.

Example:

SSL_CERT_FILE=/ssl/certs/mycert.pem

4.4.8. SSL_KEY_FILE¶

New in version 2.6.0.

Indicates the path to the server’s private key in PEM format. The default value is SSL_KEY_FILE=/etc/vpl/key.pem. From version 4.0.0, certificates can be updated without restarting the service. The file is checked every 5 minutes for modifications, and certificates are updated if necessary.

SSL_KEY_FILE=/ssl/certs/private/mykey.pem

4.4.9. CERTBOT_WEBROOT_PATH¶

New in version 4.0.3.

This parameter sets the absolute path to the root directory for serving challenge files to the web. Setting this path enables the acceptance of the challenge protocol used by Let’s Encrypt for creating and renewing certificates.

This option requires serving HTTP on port 80 (PORT=80). It is important to note that you need to set SSL_CERT_FILE and SSL_KEY_FILE appropriately. For security reasons, the server avoids serving any content other than the challenge files.

Suppose your email is my.email@gmail.com and your jail server domain name is myhostname.es. In that case, your configuration file (vpl-jail-system.conf) may contain the following options:

# Partial content of vpl-jail-system.conf
# Server domain name: myhostname.es
# Your email: my.email@gmail.com
PORT=80
CERTBOT_WEBROOT_PATH=/etc/vpl/webroot
SSL_CERT_FILE=/etc/letsencrypt/live/myhostname.es/fullchain.pem
SSL_KEY_FILE=/etc/letsencrypt/live/myhostname.es/privkey.pem

With the vpl-jail-server running, to obtain a certificate use the following command line:

sudo certbot certonly --webroot --webroot-path=/etc/vpl/webroot -m my.email@gmail.com --agree-tos -d myhostname.es

Note

This parameter makes sense if you need the service available on port 80 and also require obtaining or renewing Let’s Encrypt certificates without stopping the service.

4.5. Security parameters¶

4.5.1. URLPATH¶

This parameter acts as a password to access the execution server. If the PATH of the URL request does not match URLPATH, the request is rejected. The default value is “/”. Example:

URLPATH=secret

If this option changes, the URL of the execution server used at Moodle must be updated. URL format https://servername:SECURE_PORT/URLPATH.

4.5.2. TASK_ONLY_FROM¶

This parameter limits the servers that can do task requests. The value must be IPs or networks (type A, B, and C) separated with spaces. The IP format is the full dot notation. Example: 128.122.11.22. The network format is the incomplete dot notation ending with a dot. Example: 10.1.. The default value is empty, accepting task requests from all servers. Example:

# Accepts tasks from network 10.10.3.X and IP 192.168.1.56
TASK_ONLY_FROM=10.10.3. 192.168.1.56

4.5.3. ALLOWSUID¶

New in version 2.3.

This switch allows the execution of programs with a suid bit inside the jail. The default value is ALLOWSUID=false.

Danger

Setting this option to true may be a security breach, use at your own risk.

Example:

ALLOWSUID=false

4.5.4. FAIL2BAN¶

New in version 2.5.

VPL jail service includes a logic to ban IPs with a high number of failed requests. This feature now can be controlled with a new configuration numeric parameter called FAIL2BAN. The banning and the account of failed requests take periods of 5 minutes. If one IP does more than FAIL2BAN*20 failed requests and more failed requests than succeeded, the offending network IP is banned until the next period. Setting FAIL2BAN to 0 stops these checks. The default value of FAIL2BAN is 0. Examples:

FAIL2BAN=10

4.5.5. FIREWALL¶

Sets the system firewall using iptables. Accepted values are 0, 1, 2, 3, or 4. The preset value is 0.

No firewall
VPL service+DNS+Internet access
VPL service+DNS+Limit Internet to port 80 (super user unlimited)
VPL service+No external access (super user unlimited)
VPL service+No external access

Note

Level 4 prevents the update/upgrade of the system. You must stop the service before updating or upgrading the system.

Warning

This feature does not work in CentOS

Example:

FIREWALL=1

4.5.6. LOGLEVEL¶

This value ranges from 0 to 8. Use 0 for minimum verbosity and 8 for maximum. Level 8 doesn’t remove the prisoners’ home directory. The default value is 3. Logs are typically written to the file “/var/log/syslog”. Example:

LOGLEVEL=1

Warning

Do not use a high log level in production servers; it may reduce performance and consume disk space.

4.6. Isolation parameters¶

New in version 5.0.0.

4.6.1. USE_CGROUP¶

Enable or disable the use of CGroups to limit memory usage. The default value is true. Set to any other value to disable. This feature is not available in Docker environments.

USE_CGROUP=true

4.6.2. USE_NAMESPACE¶

Enable or disable the use of Linux namespaces for filesystem, IPC, process, and writable directory isolation. The default value is true. Set to any other value to disable. This feature requires privileged mode if running in Docker.

USE_NAMESPACE=true

4.7. File system parameters¶

4.7.1. JAILPATH¶

Sets the path to the jail directory. The system will use this directory as a fake clone of the root directory. The preset value is JAILPATH=/jail.

JAILPATH=/myjail

4.7.2. CONTROLPATH¶

Path to control directory. The system saves here information on requests in progress. The preset value is CONTROLPATH=”/var/vpl-jail-system”

CONTROLPATH="/vplcontrol"

4.7.3. USETMPFS¶

New in version 2.3.

This switch allows the use of the tmpfs file system for “/home” and the “/dev/shm” directories. The preset value is USETMPFS=true. If your system memory is low, you may set this option to false, but doing so can reduce the performance of the jail system.

USETMPFS=false

From version 2.3, the structure of jail file systems changed to improve the compatibility and performance of overlayFS usage in different OS configurations. The upper layer of the overlaid file system is on a tmpfs file system or, if you set the USETMPFS=false, is on a loop file system located at a sibling path to the control path (by default /var/vpl-jail-system.fs).

Note

If you set USETMPFS=false, you cannot set HOMESIZE to a percentage of system memory; you must set HOMESIZE to a fixed value.

4.7.4. HOMESIZE¶

New in version 2.3.

This option sets the size of the “/home” directory. The value may be a percentage of the system memory or a fixed value in megabytes (M) or gigabytes (G). The default value is 30% of the system memory. If USETMPFS is set to false, you must use a fixed value. Examples:

HOMESIZE=25%

or

HOMESIZE=1400M

4.7.5. SHMSIZE¶

New in version 2.3.

This option sets the size of the “/dev/shm” directory. The preset value is 30% of the system memory. This option is applicable when using the tmpfs file system for the “/dev/shm” directory. Example:

SHMSIZE=10%

4.8. Parameters for limiting the resources used by the requested tasks¶

These parameters set resource limits that the requested task cannot exceed.

4.8.1. MAXTIME¶

This parameter sets the maximum time for a request in seconds. Default value MAXTIME=1800

4.8.2. MAXFILESIZE¶

Maximum file size in bytes. No file created by a task can exceed this size. The default value is MAXFILESIZE=64000000.

4.8.3. MAXMEMORY¶

Maximum memory size in bytes. No running task can exceed this size. The default value is MAXMEMORY=2000000.

4.8.4. MAXPROCESSES¶

The maximum number of processes. No running task can exceed this number of processes/threads. The default value is MAXPROCESSES=500.

4.8.5. REQUEST_MAX_SIZE¶

New in version 2.7.

The maximum size of data in the request. The value can be written in bytes, kilobytes, megabytes, and gigabytes. The default value is 128 Mb.

Example:

REQUEST_MAX_SIZE=64 Mb

4.8.6. RESULT_MAX_SIZE¶

New in version 2.7.

The maximum size of data in the evaluation result. The value can be written in bytes, kilobytes, megabytes, and gigabytes. The default value is 1 Mb.

Example:

RESULT_MAX_SIZE=16 Mb

4.9. Other parameters¶

4.9.1. MIN_PRISONER_UGID¶

This parameter sets the start value for the range of user/group ids selected randomly for prisoners. The preset value is MIN_PRISONER_UGID=10000. Example:

MIN_PRISONER_UGID=11000

4.9.2. MAX_PRISONER_UGID¶

This parameter sets the end value for the range of user/group selected randomly for prisoners. The preset value is MAX_PRISONER_UGID=12000. Example:

MAX_PRISONER_UGID=11200

4.9.3. ENVPATH¶

This parameter sets the environment PATH variable when running tasks. IMPORTANT: If you are using RedHat or derived OSes, you must set this parameter to the PATH environment variable of common users (not root). The default value is empty. Example:

ENVPATH=/usr/bin:/bin

4.10. Environment Variable Configuration¶

New in version 4.0.0.

To improve the flexibility of configuration of the service, all VPL Jail System configuration parameters can be set using environment variables, which take precedence over values in the configuration file.

This feature is particularly useful for:

Containerized deployments (Docker, Kubernetes, etc.)
CI/CD pipelines where configuration needs to be dynamically set
Cloud deployments where configuration is managed externally
Development environments with different configurations per developer

4.10.1. Environment Variable Naming Convention¶

To use this feature you must set environment variable names starting with the prefix VPL_JAIL_ and continuing with the corresponding configuration parameter name in uppercase.

Format: VPL_JAIL_<PARAMETER_NAME>=<value>

Where <PARAMETER_NAME> is the uppercase version of any configuration parameter described in this document.

4.10.2. Basic Examples¶

Network configuration:

export VPL_JAIL_PORT=8000
export VPL_JAIL_SECURE_PORT=4430

This will set the plain http server port to 8000 and the secure https server port to 4430.