fireguard
CONTENT
Overview
fireguard - Firecracker MicroVMs management application. It manages VMs lifecycle (create/start/stop) and can setup a network between them so that VMs can communicate with each other as well as with host system. fireguard configures NAT so that VMs can have an access to the external network (Internet). It manages dhcpd, iptables and routing tables so that you don't need to setup them yourself.
Requirements
- Java 11
- Screen version 4.06.02 (GNU) 23-Oct-17
- firecracker v0.20.0
- jq-1.5-1-a5b5cbe
- isc-dhcp-server 4.4.1
- iproute2
Requires NOPASSWD sudo access to:
- ip
- iptables
- isc-dhcp-server
Download
You can download fireguard from here
Documentation
Configuration
Before using fireguard make sure to create configuration file ".fireguard" and place it in your $HOME location:
originVm = <ORIGIN_VM_LOCATION>
hostIface = <HOST_IFACE>
Where:
- ORIGIN_VM_LOCATION -- directory with original VM. It should be self sufficient and include everything what is needed to run a VM (kernel, vm_config.json, etc). See Quick Start for more details.
- HOST_IFACE -- host system external network interface name (so VMs can access Internet)
Usage
fireguard [ --config CONFIG_FILE ] <COMMAND>
Where:
- CONFIG_FILE is a path to fireguard config file (default is ~/.fireguard)
- COMMAND is one of the following: vm, net
vm
Work with VMs, accepts following arguments:
- create [JQ_EXPRESSION] -- create a new VM by copying ORIGIN to a STAGE. If JQ_EXPRESSION is given then update its vm_config.json with accordance to it.
- showAll -- show information about all available VMs
- start VM_ID -- start a VM with given id. Once VM is started its console available through screen utility
- stop VM_ID -- stop a VM with given id
- startAll -- start all VMs
- stopAll -- stop all VMs (right now it is done by killing the process)
- restart VM_ID -- restart VM with given id
Where:
- JQ_EXPRESSION -- it is a jq expression which will be sent to jq together with vm_config.json. It allows you to change certain VM configuration parameters.
net
Work with networks, accepts following arguments:
- create SUBNET NETMASK -- create a new network with given SUBNET and NETMASK. You cannot have two networks with same SUBNET.
- attach VM_ID NETWORK_ID -- attach virtual machine VM_ID to the network NETWORK_ID. You need to restart the VM after so it will join the network.
Examples
Configuration file
originVm = /home/ubuntu/vms/alpinelinux-3.8-kernel4.14
hostIface = enp0s3
Usage
Create new VM:
% fireguard vm create
Creating new VM...
id: vm-1
home folder: /home/ubuntu/fireguardHome/stage/vm-1
socket: /home/ubuntu/fireguardHome/stage/vm-1/firecracker.sock
state: STOPPED
pid: Optional.empty
vmConfig: path: /home/ubuntu/fireguardHome/stage/vm-1/vm_config.json
memoryGb: 1000
vcpu: 1
hostIface: Optional.empty
mac: Optional.empty
%
Start a VM:
% fireguard vm start vm-1
Starting VM with id vm-1...
%
Connect to the VM console:
% screen -r vm-1
Show all available VMs:
% fireguard vm showAll
id: vm-2
home folder: /home/ubuntu/vms/stage/vm-2
socket: /home/ubuntu/vms/stage/vm-2/firecracker.sock
state: STARTED
pid: Optional[91798]
vmConfig: path: /home/ubuntu/vms/stage/vm-2/vm_config.json
memoryGb: 8
vcpu: 1
hostIface: Optional.empty
mac: Optional.empty
id: vm-1
home folder: /home/ubuntu/vms/stage/vm-1
socket: /home/ubuntu/vms/stage/vm-1/firecracker.sock
state: STARTED
pid: Optional[91804]
vmConfig: path: /home/ubuntu/vms/stage/vm-1/vm_config.json
memoryGb: 8
vcpu: 1
hostIface: Optional.empty
mac: Optional.empty
%
Start all VMs:
% fireguard vm startAll
Starting VM with id vm-1...
Starting VM with id vm-2...
%
Restart VM:
% fireguard vm restart vm-1
Stopping VM with id vm-1...
Starting VM with id vm-1...
%
Create network
% fireguard net create 10.1.2.0 255.255.255.0
Creating new network...
id: net-1
subnet: /10.1.2.0
netmask: /255.255.255.0
ifaces: []
%
Attach vm-1 to network net-1
% fireguard net attach vm-1 net-1
Attaching vm-1 to net-1 network...
%