kathara-vstart
- Start a new Kathara device
kathara vstart
-n
DEVICE_NAME
[-h
] [--noterminals
| --terminals
| --privileged
| --num_terms
NUM_TERMS]
[--eth
<N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]]
[-e
[EXEC_COMMANDS [EXEC_COMMANDS ...]]] [--mem
MEM]
[--cpus
CPUS] [-i
IMAGE] [--no-hosthome
| --hosthome
]
[--xterm
XTERM] [--print
] [--bridged
]
[--port
<[HOST:]GUEST[/PROTOCOL]> [<[HOST:]GUEST[/PROTOCOL]> ...]] [--env
ENV [ENV ...]]
[--sysctl
SYSCTL [SYSCTL ...]] [--ulimit
<KEY=SOFT[:HARD]> [<KEY=SOFT[:HARD]> ...]] [--shell
SHELL]
Start a new device named DEVICE_NAME. Names of devices must be unique for each user. Yet, different users can run devices having the same name.
Without providing options, vstart starts a device whose configuration reflects the defaults stored inside the kathara.conf
(5) file. The options described below can be used to adjust the features of a device upon starting it.
Notice: unless differently stated, command line arguments (DEVICE_NAME) and option arguments (e.g., names of collision domains) should not contain space characters. Not complying to this causes vstart to raise an error.
-h
, --help
--noterminals
Overrides the default setting specified in kathara.conf
(5) file.
--terminals
Overrides the default setting specified in kathara.conf
(5) file.
--privileged
-n
DEVICE_NAME, --name
DEVICE_NAME
--eth
<N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]CD
: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").
/MAC_ADDR
: An optional parameter to specify the MAC address of the interface (MAC address must be in the format XX:XX:XX:XX:XX:XX
). If MAC_ADDR
is not provided, Kathara will assign a random one.
Equip the device with a network interface. N
is a positive integer starting from 0.
The network interface will be attached to a (virtual) collision domain whose name is CD
. Attaching interfaces of different devices to the same collision domain allows them to exchange network traffic. N should be declared as a sequential number, starting from 0; if any intermediate number is missing an exception is raised.
-e
[EXEC_COMMANDS [EXEC_COMMANDS ...]], --exec
[EXEC_COMMANDS [EXEC_COMMANDS ...]]Run a specific command inside the device during the startup phase. EXEC_COMMANDS are shell commands executed with the shell defined in --shell
or with the default shell defined in kathara.conf
(5).
--mem
MEM
Set the amount of available RAM inside the device to MEM. If it is not set, the device could use as much RAM as the Docker daemon can use. If you set this option, the minimum allowed value is 4m (4 megabyte).
This option takes a positive integer, followed by a suffix of "b", "k", "m", "g", to indicate bytes, kilobytes, megabytes, or gigabytes.
--cpus
CPUS
Set the amount of available CPU inside the device to CPUS. If it is not set, the device could use as much CPU as the Docker daemon can use.
This option takes a positive float, ranging from 0 to the max number of logical CPUs of the host. For instance, if the host device has two CPUs and you set --cpus
1.5, the container is guaranteed at most one and a half of the CPUs.
-i
IMAGE, --image
IMAGE
The specified Docker Image could be in the local repository or on the Docker Hub. Overrides the default setting specified in kathara.conf
(5) file.
--no-hosthome
, -H
/hosthome
directory inside devices.
Do not mount the home directory of the current user inside devices. This is the default specified in kathara.conf
(5) file.
--hosthome
/hosthome
directory inside devices.
Mount the home directory of the current user inside devices in the special directory /hosthome
. This option makes the host filesystem accessible from inside devices, overriding the default setting specified in kathara.conf
(5) file.
--xterm
XTERM, --terminal-emu
XTERM
As an example: gnome-terminal
(1). Overrides the default setting specified in kathara.conf
(5) file. This option is ignored if used in conjunction with --noterminals
or if open_terminals
is set to false.
--print
, --dry-mode
--bridged
Connect the device to the host network by adding an additional network interface (will be the last one). This interface will be connected to the host network through a NAT connection and will receive its IP configuration automatically via DHCP.
--port
<[HOST:]GUEST[/PROTOCOL]> [<[HOST:]GUEST[/PROTOCOL]> ...]If HOST port is not specified, default is 3000. If PROTOCOL is not specified, default is tcp
. Supported PROTOCOL values are: tcp, udp, or sctp.
For instance, with this command you can map host's port 8080 to device's port 80 with TCP protocol: --port "8080:80/tcp"
.
--sysctl
SYSCTL [SYSCTL ...]net.
namespace is allowed to be set.--env
ENV [ENV ...]--ulimit
<KEY=SOFT[:HARD]> [<KEY=SOFT[:HARD]> ...]Allows change of both SOFT and HARD limits. Use -1 for unlimited. If only a parameter is given, i.e. ULIMIT=SOFT, both SOFT and HARD limit will have same value.
--num_terms
NUM_TERMS
--shell
SHELL
The requested shell must be installed inside the device. Overrides the default setting specified in kathara.conf
(5) file.
kathara vstart -n pc1
Start a new device named pc1.
kathara vstart -n mypc1 -i my-image --mem 128m
Start a new device named mypc1. The device will run using local image my-image
and will be equipped with 128 MB of RAM.
kathara vstart -n producer --eth 0:A
kathara vstart -n consumer --eth 0:A
Start two devices named producer and consumer, which will be able to exchange data with each other by using their network interfaces eth0. Such interfaces will have to be configured with an IP address before the communication can actually take place.
kathara vstart -n router --bridged --eth 0:A
Start a new device named router. The device will have two network interfaces. Interface eth0 will be attached to the virtual collision domain named A and will have to be configured by hand inside the device (for example, by using ifconfig). Interface eth1 will be connected to the host network through a NAT connection.
kathara vstart -n test --eth 0:A 1:B --print
Instead of actually starting a device, check if the passed device parameters are correct.
kathara vstart -n terminal_test --xterm gnome-terminal
Start a device named terminal_test which uses the gnome-terminal terminal.
Report bugs opening an issue on the official GitHub repository where the development and maintenance is primarily done.
Issues which are security relevant should be disclosed privately to the Kathara mailing list. You do not have to be subscribed to the list to send a message there.
When reporting a bug, remember to write used commands, eventually attach your network scenario, and include the output of kathara-check
(1) in order to make possible to reproduce the bug.
Kathara was born from Netkit. Its first version was developed by Gaetano Bonofiglio and Veronica Iovinella. Currently it is mantained by Mariano Scazzariello, Tommaso Caiazzi and Lorenzo Ariemma.
People involved also include:
Copyright © 2017-2024 License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
kathara
(1), kathara-vclean
(1), kathara-vconfig
(1), kathara.conf
(5)