WIP: script to start the runtime VM
[training-lab.git] / doc / notes.txt
1 Training labs VMs
2 =================
3
4 Nesting virtual machines for fun and profit!
5
6 Things to worry about are marked below in *********************
7
8 The goal
9 ========
10
11 We have a need for an easy-to-use environment in a security training
12 lab setup. The training is designed to educate engineers about various
13 common security problems and (more importantly) how to fix them. Some
14 online training courses from Azeria labs [1] are the initial
15 exercises, but the work is expected to expand into other areas too.
16
17 The goal is simple (make it easy!), but the setup needed for this is
18 less so. We want to have have tools to provision the following:
19
20  1. a ready-to-use VM environment that engineers can deploy on their
21     existing x86-based computers (Windows/Linux/Mac), including all the
22     toolchain etc. needed for the work (called "toolchain VM" from
23     here on)
24
25  2. a further emulated machine where Arm programs can be run, tested
26     and debugged (called "runtime VM" from here on)
27
28 For simplicity of deployment, it makes sense to have the runtime VM
29 hosted *within* the toolchain VM, with automatic configuration. That
30 way, the engineers using the training labs will have one logical piece
31 to worry about: they will not need to worry about the details of
32 setting up and configuring emulation, for example.
33
34 More (obvious?) terminology: we'll call the engineer's machine the
35 "host".
36
37 [1] https://azeria-labs.com/writing-arm-shellcode/
38
39 Planning and design
40 ===================
41
42 Vagrant [2] seems to be a good fit for deploying and controlling the
43 toolchain VM. It can use a wide range of VM and container technologies
44 as a backend, but the best supported is Virtualbox [3], and that is
45 cross-platform - it can run on all three of our desired
46 platforms. Once Virtualbox is installed, Vagrant deals with all the
47 details of downloading a "box" (a configured VM image) and starting
48 it. It uses a simple "Vagrantfile" to define how a box is defined,
49 configured and provisioned. Out of the box, Vagrant sets up a shared
50 directory from the host to the box (useful for data sharing), and also
51 ssh access from the host to the box (useful for running command line
52 tools).
53
54 For our runtime VM, we will use qemu [4]. It's a powerful emulator
55 platform that supports all manner of different architectures. It can
56 run individual binaries in emulation ("qemu-user") and this uses
57 libraries etc. as normal for the emulated platform and translates
58 instructions and system calls as needed. But for our purposes it looks
59 better to run in "qemu-system" mode; this emulates a complete machine,
60 then runs a kernel and userland on top of that. While this takes a
61 little more setup initially, it's often more reliable (qemu-user is
62 known to struggle with more complicated binaries using threads, for
63 example). We'll therefore also need to provide an Arm VM image of the
64 runtime VM for qemu to use. This is a little more involved than just
65 running Vagrant, but not too difficult.
66
67 [2] https://www.vagrantup.com/
68 [3] https://www.virtualbox.org/
69 [4] https://www.qemu.org/
70
71 Expected workflow
72 =================
73
74 As Vagrant will share a directory between the host and the toolchain
75 VM, this will allow engineers to use their normal native editor and
76 other tools on their host machine, but also to use the
77 cross-toolchains in the toolchain VM to compile them for the Arm
78 target.
79
80 We will *also* try to share that same directory with the runtime
81 VM. That will give us a simple view of the whole project in terms of
82 editing, building and running code. 
83
84 Deployment should be as simple as possible. It might be time-consuming
85 on first run due to the need to download two VM images, but that's OK
86 so long as they're not *too* big. The Vagrantfile for the toolchain VM
87 will be the only piece needed by the end user, and it should be
88 responsible for doing everything else from there down:
89
90  1. Create and run a Virtualbox VM, using an existing stable Ubuntu
91     image. This is trivial out-of-the box Vagrant usage.
92
93  2. Configure that VM for data sharing and access to the toolchain
94     VM. Again, this is common Vagrant usage.
95
96  3. Inside the toolchain VM, apply any updates that might be needed
97     then install the extra packages we need (qemu and
98     cross-toolchains)
99
100  4. Download the runtime VM image from our own source (TBD, probably
101     Sharepoint somewhere?)
102
103  5. Start the runtime VM image and *also* set up data sharing and
104     access to it. This will need a little bit more configuration in
105     Vagrant, but should be simple enough.
106
107  6. Download the desired training materials - source code, docs, etc.
108
109  7. Tell the user that they're good to go. Point to the start of the
110     training material
111
112 ************************************
113 Step #5 is (by far) the hardest piece here. Either we need to
114 preconfigure the runtime VM in certain ways, *or* we'll need to
115 download a generic image and modify/configure it in the field before
116 we start it. The first option is easier to achieve for now, and much
117 faster to deploy - we don't end up installing packages at runtime onto
118 an emulated system. BUT: it also means that we'll have to maintain
119 that runtime VM image separately rather than using a generic image. If
120 we deploy multiple different sets of training material using this
121 setup, we could end up having to maintain multiple slightly-different
122 versions of the runtime VM.
123 ************************************
124
125 Technical details and (possible) troubles
126 =========================================
127
128 SSH access
129 ----------
130
131 As it starts the toolchain VM, Vagrant generates a throwaway SSH
132 key. It stores the private key in
133
134   .vagrant/machines/default/virtualbox/private_key
135
136 and injects the public key into the toolchain VM at startup. It is
137 stored under /home/vagrant/.ssh/authorized_keys, as you'd normally
138 expect for ssh key access. Vagrant also sets up port forwarding
139 between port 2222 of the host machine and port 22 on the toolchain
140 VM. "vagrant ssh" is then a simple wrapper around ssh to use the right
141 key, username and IP address etc.
142
143 We can borrow some of the same setup for the runtime VM. When starting
144 it from inside the toolchain VM, we can copy the SSH public key into
145 the shared data directory /vagrant. We can set up port forwarding
146 within the toolchain VM too, and expose that in the
147 Vagrantfile. Arbitrarily, let's use port 2223 for the ssh connection
148 to the runtime VM. That will give us the following port usage:
149
150   HOST     TOOLCHAIN VM     RUNTIME VM
151   2222 <-> 22               ---
152   2223 <-> 2222         <-> 22 
153
154 It's worth adding a single wrapper script to make the ssh calls more
155 consistent, rather than "vagrant ssh" for the toolchain VM and
156 something different / more complicated for the runtime VM.
157
158 Data access
159 -----------
160
161 By default, Vagrant shares the "project" directory (i.e. the directory
162 where the Vagrantfile lives) into the toolchain VM as /vagrant
163 [5]. This is a really useful feature. We can extend this feature
164 ourselves, sharing the same directory from the toolchain VM to the
165 runtime VM. To do that, we use qemu's built-in support for a "Plan 9"
166 filesystem export (the "-virtfs" command line option). Then we mount
167 that filesystem inside the runtime VM on /vagrant too.
168
169 This will give the user a consistent easy place to share their data,
170 e.g. when compiling and running test programs. We can also use it for
171 our own internal purposes, e.g. for sharing the SSH authorized_keys
172 file.
173
174 We will also try to download and store the runtime VM image and
175 associated files here. That will save us having to make space for them
176 inside the small toolchain VM.
177
178 ************************************
179 I'm *not* sure how well this will work in performance terms - how
180 fast is the virtualbox shared filesystem? Testing needed...
181 ************************************
182
183 [5] https://www.vagrantup.com/intro/getting-started/synced_folders.html
184
185 Setup of the toolchain VM
186 -------------------------
187
188 This *should* be trivial, given the idea behind Vagrant. It's just a
189 case of generating a Vagrantfile with some config in it. Put that in a
190 git repo and tell the user:
191
192  * install vagrant, virtualbox and git for their OS
193  * git pull <foo> lab.git
194  * cd lab.git
195  * vagrant up
196
197 ************************************
198 However, things did not work quite so smoothly during development. For
199 the directory-sharing feature that we're expecting to use, Virtualbox
200 depends on its guest (our toolchain VM) having a guest utilities
201 package installed ("virtualbox-guest-utils" on Ubuntu"). Initial
202 testing with a Debian image did not work. Virtualbox started up (with
203 warnings about a version mismatch). Annoyingly, Vagrant apparently
204 noticed the failure and fell back to using a one-time rsync at VM
205 startup. This gave the appearance of working sharing, but did not stay
206 in sync. I've added extra config to the Vagrantfile to force *only*
207 Virtualbox-style sharing.
208
209 Testing with some other Ubuntu boxes also failed - I tried a few
210 variants of the (very new!) 20.04 release and they exhibited a range
211 of problems giving unreliable startup. I've switched to 18.04 (aka
212 "ubuntu/bionic64") and so far that has worked flawlessly.
213 ************************************