5.4 KiB
VMMgr command line hooks
VMMgr is mostly a WSGI web GUI application, but there are few specific cases when it is invoked via command line.
Installation hooks
register-app
This hook is invoked by Package manager, resp. install.sh script of the respective installing package. It is invoked as
vmmgr register-app <application> <subdomain> [admin-username] [admin-password]
Where the application is the internal application name, same as previously used in the package name, subdomain is the subdomain on which the application will be accessible and the admin-username and admin-password are optional admin credentials created by install.sh during the application setup. These parameters will show up as part of the application definition in /etc/vmmgr/conf.json and will be visible / usable via web GUI.
unregister-app
Counterpart to register-app. This hook is invoked by uninstall.sh and simply removes the application definition from /etc/vmmgr/conf.json, rendering it invisible / unusable via web GUI, which is expected as part of the uninstallation process. It is invoked as
vmmgr unregister-app <application>
Where the application is the internal application name, same as previously used in the package name.
LXC hooks
LXC hooks set various environment variables prior to calling the defined executables. For overview of native LXC hooks, see section Container hooks in the official lxc.container.conf(5) documentation. All hooks mentioned in this chapter are hardcoded in the container configuration via a template used bylxcbuild.
prepare-container
This hook is invoked by LXC's lxc.hook.pre-start, which is called in host environment (i.e. in the virtual machine, not in the container) before the container's ttys, consoles or mounts are up. This hook removes the contents of container's ephemeral OverlayFS layer in case of previous unclean container shutdown. Then calls application's update-conf.sh script (if it is present) with environment variables populated from configuration in /etc/vmmgr/conf.json, allowing for the correct configuration of application in components which are not part of the currently starting container, e.g. application URL in a database or persistent configuration file. It is invoked as
vmmgr lxc-container
The hook expects the LXC_NAME environment variable to be populated.
register-container
This hook is invoked by LXC's lxc.hook.start-host which is called in host environment (i.e. in the virtual machine, not in the container) after the container has been setup, immediately before launching the container's init process. This hook sets up a container's network settings (IP address, netmask, default route). The network settings is managed via poor man's DHCP server, which simply assigns the first unassigned IP address from range 172.17.0.0/16 and holds the lease table in hosts's /etc/hosts which is also mounted in all containers, keeping the network settings consistent across all container stop / starts. The hook is invoked as
vmmgr register-container
The hook expects LXC_NAME and LXC_PID environment variables to be populated, so it can record the value of LXC_NAME into /etc/hosts leases and then nsenter the container namespace via LXC_PID and set the leased address.
unregister-container
This hook is invoked by LXC's lxc.hook.post-stop which is called in host environment (i.e. in the virtual machine, not in the container) after the container has been shut down. This hook releases the IP address leased by register-container and then removes the contents of container's ephemeral OverlayFS layer. It is invoked as
vmmgr unregister-container
The hook expects the LXC_NAME environment variable to be populated.
Init hooks
rebuild-issue
This hook is called by /sbin/vmtty, which is the default login program used by /sbin/getty defined in /etc/inittab. This tty contains a banner with branding, legal notice and information about VM network settings and URL, stored in /etc/issue. The URL needs to be generated based on the settings in /etc/vmmgr/conf.json, which is exactly what this hook does. On every invocation, it regenerates the contents of /etc/issue with up-to-date information. The hook is invoked as-is with no parameters or environment variables.
vmmgr rebuild-issue
register-proxy
This hook is invoked by /etc/init.d/<application> OpenRC init script as part of start_post() function. It is invoked as
vmmgr register-proxy <application>
The hook creates HTTP proxy configuration file for VM's nginx HTTP server for the given application, based on the settings in /etc/vmmgr/conf.json. Then it reloads the nginx service to take the configuration into effect. The proxy configuration requires a valid IP/hostname in /etc/hosts, which exists only after the container has been started and register-container hook called, hence the post-start invocation.
unregister-proxy
Counterpart to register-proxy. This hook is called by /etc/init.d/<application> OpenRC init script as part of stop_pre() function. It is invoked as
vmmgr unregister-proxy <application>
The hook simply removes the configuration file for VM's nginx HTTP server for the given application and reloads the nginx service to take the configuration out of effect.