Using Tmux With Netkit-JH
Installing Tmux#
Tmux is available in most package managers - install with your package manager:
- Debian / Ubuntu
- Arch Linux
Configure Netkit to use Tmux#
There are two ways to enable tmux with Netkit-JH: using options in netkit.conf, or through commandline arguments to lstart or vstart.
Netkit.conf#
Edit the file at $NETKIT_HOME/netkit.conf and look for the following options:
VM_CON0 specifies what type of console to use as the primary console for the Netkit VM. This can be changed to VM_CON0=tmux to wrap the console in a tmux session.
TMUX_OPEN_TERMS specifies whether a terminal should be automatically opened for the machine after the tmux session is created. This means at the end of the machine startup script, the vconnect command is run to attempt to connect to the tmux session in a new terminal. This will use the terminal specified by TERM_TYPE in your config. This will retry every 5 seconds, up to 20 times. If no tmux session exists by then, it will fail. If your startup takes a long time, you can always vconnect manually if this times out. TMUX_OPEN_TERMS can have a value of 'yes' or 'no', however if the option given is invalid the behaviour will default to it being disabled. When TMUX_OPEN_TERMS is set to 'yes', you must be running the lstart / vstart command within a graphical environment, as it will attempt to open a graphical terminal. If it is 'no', you can still connect manually with vconnect -m MACHINE - which is useful if you are running headless, for example through an SSH session.
Commandline Arguments#
The following arguments are available for both lstart and vstart.
--tmux-attached - this runs machines with VM_CON0=tmux and TMUX_OPEN_TERMS=yes (see netkit.conf section above for what these variables do)
--tmux-detached - this runs machines with VM_CON0=tmux and TMUX_OPEN_TERMS=no (see netkit.conf section above for what these variables do)
How Use Tmux with Netkit-JH#
Connecting To A Machine#
First check what machines you can connect to:
We see that there is a tmux session for machine a. We can connect to it with:
Now a new terminal should appear (the terminal specified by TERM_TYPE in netkit.conf). If you want to connect in the current terminal / shell (necessary if you're running headless) you can omit the --terminal.
If you have TMUX_OPEN_TERMS=yes in your netkit.conf, or pass --tmux-attached to lstart or vstart, you shouldn't have to connect to the machine manually. However you might want to disconnect after a terminal has auto-opened, and then connect to it again later - the above is how you would do this.
General Tmux Use#
In tmux, most keyboard shortcuts require you to hit a 'leader' key, followed by a key specific to the shortcut. The current leader key we have configured is ctrl + t. This means to run a tmux shortcut you would do ctrl + t, then press the key for the command.
Where you see leader, remember this means ctrl + t, unless you're using a custom tmux config.
info
Here we've used ctrl + t for the leader key, as ctrl + b is the default for tmux, and some people might want to connect to a machine's tmux session within a tmux session on the host, e.g. having different machines in different panes. Another popular leader key is ctrl + a, which is also the default leader key for GNU Screen - meaning this would also conflict. We thought ctrl + t would have the least conflicts and therefore be a good leader key, but if you want to propose a better default please open an issue on GitHub!
Disconnecting from a machine#
To disconnect from a tmux session, press leader then d. This will disconnect you from the session without closing it, so you can reconnect at any point while the machine is running.
Show Help Message#
There is a simple help file, with similar information to what is in this docs, which you can access within a Netkit Tmux session by pressing leader then h
The Netkit VM Pane#
The Netkit VM will run under window 'netkit-vm' pane '0'. If you are not on this pane all commands will go to the host not the Netkit machine!!
To help you, the status bar should change colour depending on what pane you are in. By default this is purple if you are in a netkit vm and blue if you are in a host shell.
Creating New Panes#
To create a new pane do leader followed by % - this will create a vertical split.
If you want a horizontal split instead, you can use leader followed by "
To move between panes you hit leader followed by arrow-key - with the arrow key depending on the direction you want to move from the current active pane. You also may be able to click on a with your mouse to move to it (depending on your terminal).
If you have made a split / splits, you may want to zoom into a specific pane. By hitting leader followed by z you will zoom into the active pane (the active pane will fill the whole window). To zoom out, just do this again.
Creating new windows#
To create a new window, do leader followed by c. This will create a window to the right of the current window.
To move between windows you can use leader n to go to the next window, or leader p to go to the previous.
Capturing Output#
Note the following will save the active pane, so if you want to capture the machine log, make sure you are on the netkit pane!
To save output to /tmp hit leader then s (lower case 's').
To save with a custom filename, use leader S (capital 'S').
Netkit Machine Shutdown / Failure#
When a machine shuts down it can be due to errors that we need to look at. In order to preserve the machine output, the tmux session will get renamed to MACHINENAME-dead, and the netkit pane will remain open.
Custom Config File#
If you would like to customise tmux, the best way is to create a config file at $NETKIT_HOME/tools/tmux.conf.custom. For guidance on customising tmux, check out this blog post, and the tmux man page.
Advanced#
If you want to automate starting labs with tmux, take a look at the blog post about tmuxinator.
You can start using tmux with netkit without having to learn lots about tmux to begin with, but tmux can be more powerful if you learn more about windows, panes, shortcuts etc. Once you have a basic understanding of tmux you might find the following resources useful for getting a deeper understanding: