FreeBSD Manual Pages
LITTLEJET(1) General Commands Manual LITTLEJET(1) NAME littlejet -- Create, deploy, manage and scale FreeBSD jails anywhere SYNOPSIS littlejet usage littlejet version littlejet add-label project node label=value ... littlejet del-label project node label littlejet del-labels project node littlejet get-label project node label littlejet get-labels project node littlejet add-node [-T] project node littlejet copy-nodes [-O] src-project dst-project [node] littlejet del-node project node littlejet del-nodes project littlejet copy [-fN] project new-project littlejet create [-f] project [director-file] littlejet destroy project littlejet get-nodes project littlejet get-projects littlejet rename project new-project littlejet show [project] littlejet run-appjail [-CHPs] [-p project] [-n node] appjail-command [args ...] littlejet run-cmd [-CHPs] [-p project] [-n node] command [args ...] littlejet run-director [-CHPs] [-p project] [-n node] director-command [args ...] littlejet run-script [-p project] run-script [args ...] littlejet schedule lock-file args ... littlejet set-director project director-file littlejet set-env project env-file DESCRIPTION LittleJet is an open source, easy-to-use orchestrator for managing, deploy- ing, 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 un- less 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 contin- ues 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 com- pleted, project is removed. show [project] Displays information about project or all projects if none are speci- fied. 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 mean- ingless when the -p and -n parameters are set since the given com- mand 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 suf- fixes. 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 Run- Script. 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 parame- ter. 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 para- meter 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 exist- ing 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 de- stroy 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 connec- tor 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> de- faults to -wg. -v virtual-network AppJail virtual network created by appjail-network(1). By de- fault, 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 be- tween 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 de- fault, 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 bal- ancer 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 de- tails. Nodes can be excluded using the vpn.wg.load-balancer.pen.exclude la- bel. 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 de- fault, 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 JesAos Daniel Colmenares Oviedo <DtxdF@disroot.org> FreeBSD ports 15.quarterly July 1, 2024 LITTLEJET(1)
NAME | SYNOPSIS | DESCRIPTION | RUNSCRIPTS | FILES | EXIT STATUS | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=littlejet&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>