NAME

littlejet — Create, deploy, manage and scale FreeBSD jails anywhere

SYNOPSIS

DESCRIPTION

LittleJet is an open source, easy-to-use orchestrator for managing, deploying, scaling and interconnecting FreeBSD jails anywhere in the world.

The options are as follows:

usage

Display usage message and exit.

version

Display version information about LittleJet.

add-label project node label=value ...

Add a new label to an existing project node.

del-label project node label

Delete an existing label from the given project node.

del-labels project node

Delete all labels from the given project node.

get-label project node label

Get the label value from the project node.

get-labels project node

Get all labels from the project node.

add-node [-T] project node

Add a new node to project. By default, this subcommand connects to the node and runs the true(1) command to check if everything is OK unless the -T flag is set.

copy-nodes [-O] src-project dst-project [node]

Copy nodes from src-project to dst-project.

If the -O flag is set, nodes in dst-project are deleted first before nodes in src-project are copied.

If a node is specified, it is only copied instead of all nodes.

del-node project node

Remove node from project. This also destroys the project remotely.

del-nodes project

Like del-node but for each node of project.

copy [-fN] project new-project

Copy project as new-project.

By default, nodes are copied unless the -N flag is set.

If the -f flag is set and new-project exists, it will be overwritten.

create [-f] project [director-file]

Create a new project.

This subcommand first determines the directory of the Director file and makes a complete copy. That new copy is the new project directory. By default, the Director file is “appjail-director.yml”, assuming one exists in the current working directory.

An error is returned if the project to be created exists unless -f is set.

destroy project

Destroys the nodes of the given project and the project itself. It will destroy the project remotely on each node, which means that all its jails will be destroyed.

Note that this subcommand will attempt to destroy jails, but if the current jail fails to be stopped or destroyed, this subcommand continues without problems and ignores those jails.

get-nodes project

Get a list of the current nodes for the given project.

get-projects

Get a list of current projects.

rename project new-project

Rename a project.

Technically, this subcommand first copies project as new-project and then copies the nodes of project. Once these operations are completed, project is removed.

show [project]

Displays information about project or all projects if none are specified.

run-appjail [-CHPs] [-p project] [-n node] appjail-command [args ...]

 

run-cmd [-CHPs] [-p project] [-n node] command [args ...]

 

run-director [-CHPs] [-p project] [-n node] director-command [args ...]

Run an appjail(1) subcommand with run-appjail, a Director subcommand with run-director, or simply a shell command on the remote system with run-cmd.

If -p and -n are not set, the given command is executed on each node in each project.

For each execution of the run-director subcommand, it sets the DIRECTOR_PROJECT and LITTLEJET_NODE environment variables.

-C

Since the ssh(1)'s -t flag is set, the output will be altered, so sansi(1) is used to remove those control characters.

Note that this command must put stdout/stderr into a buffer before displaying it.

-H

By default, a header is displayed to see where the next host should execute the given command, unless this flag is set.

-P

The given command is executed linearly on each node, but with this flag it is executed in parallel on each node. This flag is meaningless when the -p and -n parameters are set since the given command is executed as if this flag were not set.

-s

Exits without success when the given command fails. This only makes sense when the -P flag is not set.

Note that this command must put stdout/stderr into a buffer before displaying it.

-p project

Run the given command in the given project. If the -n parameter is not set, the command is run on each node in this project.

-n node

Run the given command on the given node. If the -p parameter is not set, the command is executed in each project but using this node.

run-script [-p project] run-script [args ...]

Run the given RunScript on all projects or on the specific project if -p is set.

schedule lock-file args ...

If there is another process locking lock-file, this subcommand will exit immediately and successfully. This subcommand is very useful when run with a tool like cron(8).

set-director project director-file

Set a new Director file by overwriting an existing one in the project directory.

set-env project env-file

Copy new environment file by overwriting an existing one in the project directory.

RUNSCRIPTS

deploy.all

Deploy the project to all nodes in parallel.

deploy.all.seq

Deploy the project to all nodes sequentially.

deploy.each

For each run, deploy to any of the nodes.

deploy.once

Deploy a project to a node if it is not already deployed to any of them.

deploy.random

Deploy a project to a randomly chosen node.

deploy.scale [-m min] [-M max] [-r rctl-rules] [-S number] [-t scale-type] [-T number]

Scale the project.

Note that this RunScript can and will destroy the project regardless of the node.

-m min

Minimum of replicas. By default is 1.

-M max

Maximum replicas that the project can replicate when auto-scaling. By default is the same than the total of nodes in the given project.

-r rctl-rules

Space-separated list of rctl(8) rules. Each item is a key and value pair separated by =. The key is an rctl(8) resource. You can use the suffixes described in humanize_number(3) for resources that work with bytes and any resources with numbers without suffixes. Regardless of whether the resource works with bytes or any other unit, the value must be greater than 0.

Note that the value is interpreted based on the scale type set by the -t parameter.

Each node must pre-configure kern.racct.enable=1 in its loader.conf(5) before using any rctl(8) rules.

-S number

Stabilization window.

After there are no more targets (projects or jails) that fail the rctl(8) rules, this RunScript will destroy the rest of the nodes up to the minimum defined by the -m parameter. This parameter will sleep the current process at the given number if it is greater than 0 before re-performing the entire operation of this RunScript.

The default is 30.

-t scale-type

How the value defined by the rctl(8) rule in the -r parameter should be interpreted to check whether a target (project or jail) passes the test or not.

any-jail

Fails if any of the jails have a metric greater than or equal to the limit defined by the -r parameter.

This is the default.

any-project

Fails if the metric total for all jails in the same project is greater than or equal to the limit defined by the -r parameter.

average

Calculates the average of the metric for all jails in the same project and fails if it is greater than or equal to the limit defined by the -r parameter.

percent-jail=percent

Calculates the percentage of the limit defined by the -r parameter and fails if it is greater than or equal to the current metric. For example, if you define a rule as “vmemoryuse=512m” and a percentage of 60, the value will be 307 (rounded), so this test fails if the current metric is greater than or equal to 307.

percent-project=percent

Like percent-jail, but first get the metric total for all jails in the same project.

-T number

After deploying to a new node due to a failed test of an rctl(8) rule against another target (project or jail), sleep up to the number defined by this parameter.

The default is 15.

deploy.single node

Deploy a project to the given node.

vpn.wg.client [-j jail] [-n node] [-s suffix] [-v virtual-network] vpn

Create a “Connector”, a jail with a VPN client connected to the VPN server that can forward packets between a service in another jail and the VPN.

A jail that wants to be exposed to the VPN must configure vpn.wg.client.include.me as one of its labels. Also required is vpn.wg.client.from.port, which is the port the load balancer will use to send packets. Other labels are vpn.wg.client.target.port which by default, when not defined, is the same as vpn.wg.client.from.port, and finally, vpn.wg.client.proto, the service protocol, which by default is tcp.

You must first deploy the VPN server using the RunScript vpn.wg.server. After deployment, vpn should point to that node. This RunScript also does not include the project even if you pass an existing one, but it is recommended to pass at least one non-existent project as ignore at least so as not to execute this RunScript several times up to the total number of projects that the manager has.

This RunScript is designed to be executed more than once. If you run again after a previous successful deployment, this RunScript will check if the jail that has the service exists and if not, it will destroy the connector and remove the peer from the VPN. It will also check if the jail that has the service has changed its IPv4 address of the Virtual Network and if so it will update the IPv4 that the connector uses to send packets to that jail to finally reload the pf(4) rules.

Nodes can be excluded using the vpn.wg.client.exclude label. See add-label for more details. Note that this label is ignored when -n is set.

-j jail

vpn's jail.

The default is littlejet-server-wg.

-n node

Work only on this node.

-s suffix

The “Connector” is a jail with a VPN client and needs a name. The jail name will be <project>-<service><suffix>, where <suffix> defaults to -wg.

-v virtual-network

AppJail virtual network created by appjail-network(1). By default, this is undefined, so appjail-quick(1) will use the AUTO_* network parameters to create one if it doesn't exist.

vpn.wg.client.destroy [-j jail] [-n node] [-s suffix] vpn

Destroy all already deployed connectors. This also requires the VPN server to be deployed for this RunScript to remove the association between the connectors and the peers.

The vpn.wg.client.exclude node label can be used to ignore the given node, but note that this is ignored when -n is set.

vpn.wg.server [-E] [-j jail-name] [-p port] [-n network] [-m mtu] [-P seconds] [-v virtual-network] -e endpoint node

Create a VPN server on node.

See also VPN server, VPN client and Load balancer

It is necessary to load if_wg(4) on each node (including the VPN server) before using this and other vpn.wg.* RunScripts. Add it to your loader.conf(5) file to load it at boot.

-E

By default, the port will be exposed unless this flag is set.

-j jail-name

Jail name where the VPN server will be.

The default is littlejet-server-wg.

-p port

VPN server port. By default is 51820.

-n network

VPN address.

-m mtu

See MTU in wg-quick(8).

-P seconds

See PersistentKeepalive in wg(8).

-v virtual-network

AppJail virtual network created by appjail-network(1). By default, this is undefined, so appjail-quick(1) will use the AUTO_* network parameters to create one if it doesn't exist.

-e endpoint

IP address of the VPN node.

Note that deploying the VPN server, connectors, and/or load balancer on the same node will not work if you use the external IP address of the VPN node.

See Redirection and Reflection

vpn.wg.server.destroy [-j jail-name] node

Destroy the VPN jail jail-name, which by default is littlejet-server-wg, on node node.

If you want to destroy all the load balancers, connectors and the VPN server, you must run the corresponding RunScripts in that order.

vpn.wg.load-balancer.pen [-eHhrsWP] [-b seconds] [-c number] [-J jail] [-m number] [-n node] [-p port] [-S suffix] [-T seconds] [-t seconds] [-q backlog] [-v virtual-network] [-x number] vpn node

Create a jail with a load balancer that also provides failover and a VPN client that connects to the VPN server vpn for each service that wants to load balance on node.

Jails that want to load balance must have the vpn.wg.load-balancer.pen.include.me label and at least vpn.wg.client.from.port configured. vpn.wg.client.client.proto will be used if set.

There are other node labels that are more useful depending on the load balancing algorithm you choose. vpn.wg.load-balancer.pen.max, vpn.wg.load-balancer.pen.hard, vpn.wg.load-balancer.pen.weight and vpn.wg.load-balancer.pen.prio. See server in penctl(1) for more details.

Nodes can be excluded using the vpn.wg.load-balancer.pen.exclude label. See add-label for more details. Note that this label is ignored when -n is set.

Remember that pen(1) is an L4 load balancer, so if all nodes are dead or the service is not provided on any node, the client will see empty replies or just errors.

This RunScript is designed to be executed more than once. If run after a successful deployment, it will update the current list of servers to include more, the same, or fewer nodes than the previous deployment, but note that this list is updated dynamically and if you restart pen(1) or the jail that once you have it, it will start with the server list you started with the first time. Since the process will be repeated, the list will be up-to-date.

-e

Expose the service provided by the load balancer.

For each load balancer created and when the -e flag is set, the port is incremented, so for example, if there are two services to load balance and the initial port is 1234, then the first load balancer will use 1234 and the second 1235.

-H

See -H in penctl(1).

-h

See -h in pen(1).

-r

See -r in pen(1).

-s

See -s in pen(1).

-W

See -W in pen(1).

-P

See prio in penctl(1).

-b seconds

See -b in pen(1).

The default is 6.

-c number

See -c in pen(1).

The default is 2048.

-J jail

vpn's jail.

The default is littlejet-server-wg.

-m number

See -m in pen(1).

The default is 256.

-n node

Work only on this node.

-p port

Listening port.

The default is 1234.

-S suffix

The load balancer is a jail that needs a name. The jail name will be <project>-<service><suffix>, where <suffix> defaults to -lb.

-T seconds

See -T in pen(1).

The default is 6.

-t seconds

See -t in pen(1).

The default is 10.

-q backlog

See -q in pen(1).

The default is 500.

-v virtual-network

AppJail virtual network created by appjail-network(1). By default, this is undefined, so appjail-quick(1) will use the AUTO_* network parameters to create one if it doesn't exist.

-x number

See -x in pen(1).

The default is 500.

vpn.wg.load-balancer.pen.destroy [-J jail] [-n node] [-S suffix] vpn node

Destroy all already deployed load-balancers. This also requires the VPN server to be deployed for this RunScript to remove the association between the load-balancers and the peers.

The vpn.wg.load-balancer.pen.exclude node label can be used to ignore the given node, but note that this is ignored when -n is set.

FILES

~/.config/littlejet/config.conf

See littlejet.conf(5).

/usr/local/share/littlejet/files/lib.subr

Subroutines primarily used by RunScripts.

EXIT STATUS

The littlejet utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

appjail(1) sysexits(3) littlejet.conf(5) AppJail Director

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>