README.md 3.76 KB
Newer Older
Jan Vykopal's avatar
Jan Vykopal committed
1
2
# sandbox-creator

Attila Farkas's avatar
Attila Farkas committed
3
4
5
A next generation of https://gitlab.ics.muni.cz/KYPO-content/KYPO-Creator


Attila Farkas's avatar
Attila Farkas committed
6
generate.py is a python program that generates a vagrant source file from a definition in yaml. This yaml file contains definitions of devices (hosts and routers) and networks. Its structure is described below.
Attila Farkas's avatar
Attila Farkas committed
7
8
9
10

### Usage:
1. Clone the project.
2. Navigate to the project folder.
Attila Farkas's avatar
Attila Farkas committed
11
3. Type `$ python3 generate.py yaml_file.yml`. There is a test yaml file in the repository called test.yml.
Attila Farkas's avatar
Attila Farkas committed
12
13
4. Run `$ vagrant up`

Attila Farkas's avatar
Attila Farkas committed
14
### Input yaml file structure
Attila Farkas's avatar
Attila Farkas committed
15

Attila Farkas's avatar
Attila Farkas committed
16
17
18
19
20
- `hosts`: a list of host devices. All attributes of these virtual machines are defined here. Every host must have a unique `name` and a `base_box`.
	- `name`: unique name of the device (required)
	- `base_box`: an OS image that will be installed on the machine (required)
	- `cpus`: number of CPU units
	- `memory`: required memory size in MB
Attila Farkas's avatar
Attila Farkas committed
21
	- `flavor`: a quick definition of memory and cpus (details below)
Attila Farkas's avatar
Attila Farkas committed
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
	- other simple [vagrant attributes](https://www.vagrantup.com/docs/vagrantfile/machine_settings.html)

- `routers`: a list of routers. Routers need only a unique name. All other attributes are preset (Debian 10 with 256MB memory and 2 CPUs).
	- `name`: a unique router name (required)

- `networks`: list of networks
	- `name`: unique name of the network (required)
	- `cidr`: ip address of the network in cidr notation

- `net_mappings`: mappings of host machines to a network. This list defines the ip addresses of host in certain networks
	- `host`: name of an existing host
	- `network`: name of an existing network
	- `ip`: ip address of the host in the network

- `router_mappings`: similar to net_mappings. It defines the addresses of routers inside networks.
	- `router`: name of an existing router
	- `network`: name of an existing network
	- `ip`: ip address of the router in the network
Attila Farkas's avatar
Attila Farkas committed
40

Attila Farkas's avatar
Attila Farkas committed
41
42
43
44
45
46
47
48
### Testing the network

After a successful `vagrant up` it is sometimes needed to test the network routing:

1. Log in to a host with `$ vagrant ssh <host>`.
2. Ping a host from a different network with `$ ping <other-host>`.
3. If the networks are connected with a router and the routing works, ping gives an output (cca every second) about the transmitted packets. If ping cannot access the other host, no such output is produced.

Attila Farkas's avatar
Attila Farkas committed
49
#### Flavors
Attila Farkas's avatar
Attila Farkas committed
50

Attila Farkas's avatar
Attila Farkas committed
51
52
53
Flavors provide a quick way to choose hardware specs (like number of cpus and memory) for a virtual machine. These attributes can also be specified separately by `memory` and `cpus`. The values of `memory` and/or `cpus` always override the values specified in the `flavor`.

##### Supported flavors:
Attila Farkas's avatar
Attila Farkas committed
54
55
56
57
58
59
60
61
62
63
64
65
66
| flavor | cpus | memory |
| ------------------ |:--:|:-----:|
| csirtmu.tiny1x2    | 1  | 2048  |
| csirtmu.tiny1x4    | 1  | 4096  |
| csirtmu.small2x4   | 2  | 4096  |
| csirtmu.small2x8   | 2  | 8192  |
| csirtmu.medium4x8  | 4  | 8192  |
| csirtmu.medium4x16 | 4  | 16384 |
| csirtmu.large8x16  | 8  | 16384 |
| csirtmu.large8x32  | 8  | 32768 |
| csirtmu.jumbo16x32 | 16 | 32768 |
| csirtmu.jumbo16x64 | 16 | 65536 |

Attila Farkas's avatar
Attila Farkas committed
67
68
69
70
71
72
73
74
75
76
### Implemented attribute types:
- all simple vagrant attributes
- flavors, memory, cpus
- a simple network (assigning ip and netmask to a device)
- simple routing (one router between networks)

### Not implemented yet:
- other VirtualBox attributes
- more complex routing

Attila Farkas's avatar
Attila Farkas committed
77
78
79
80
81
### Known [issues](https://gitlab.ics.muni.cz/cs4eu/sandbox-creator/issues):
- after running on Windows the output may contain invalid multibyte chars

### Notes
- tested on Vagrant 2.2.5, VirtualBox 6.0.4 and 6.0.10
82
- Vagrantfile and the provision directory contains everything needed by vagrant. Feel free to move them to a different directory after creation. 
Attila Farkas's avatar
Attila Farkas committed
83

Attila Farkas's avatar
Attila Farkas committed
84
85
### Other requirements
- DHCP server for vboxnet0 must be turned off in VirtualBox. It can be done manually in VirtualBox or with the command `$ VBoxManage dhcpserver remove --ifname vboxnet0`