COMP3301 Episode 3: Return of the Sys

COMP3301 Semester 1 2024 Assignment 1
COMP3301 Assignment 11
OpenBSD Zones “Episode 3: Return of the Sys(call)”2
Due: 3pm Monday in Week 5(19th of August)3
Submission: BlackBoard (reflection) and Git.4
Demo and git are marked in your lab session in week 55
Last Updated: July 30, 20246
1 Academic Integrity7
All assessments are individual. You should feel free to discuss aspects of C programming and8
assessment specifications with fellow students and discuss the related APIs in general terms.9
You should not actively help (or seek help from) other students with the actual10
coding of your assessment. It is cheating to look at another student’s code, and it is11
cheating to allow your code to be seen or shared in printed or electronic form. You should note12
that all submitted code will be subject to automated checks for plagiarism and collusion. If we13
detect plagiarism or collusion (outside of the base code given to everyone), formal misconduct14
proceedings will be initiated against you.15
If you’re having trouble, seek help from a teaching staff member. Do not be tempted to copy16
another student’s code. You should read and understand the statements on student misconduct17
in the course profile and on the school website: https://eecs.uq.edu.au/current-students/18
guidelines-and-policies-students/student-conduct.19
1.1 Use of AI Tools20
All assessment tasks evaluate students’ abilities, skills and knowledge without the aid of gen-21
erative Artificial Intelligence (AI) or Machine Translation (MT). Students are advised that the22
use of AI technologies to develop responses (e.g. code generation) is strictly prohibited and23
may constitute student misconduct under the Student Code of Conduct.24
2 Introduction25
This assignment will extend a basic implementation of “zones” in the OpenBSD kernel. The26
main area of improvement will be separating group and user permissions on zone operations.27
You will be provided with a diff that adds the basic zones functionality to OpenBSD. You will28
need to make changes and improvements on top of this diff.29
The purpose of this assignment is for you to demonstrate an understanding of the role of an30
operating system kernel and how it supports processes making system calls, as well as your31
skills in reading, understanding, and modifying existing code.32
Page 1 of 11
COMP3301 Semester 1 2024 Assignment 1
2.1 Background33
Zones extend the isolation of processes beyond what is traditionally provided by UNIX and34
UNIX-like systems, including OpenBSD. Traditionally, all processes running on an OpenBSD35
are visible to all other processes. This can be demonstrated by running commands like top(1),36
ps(1), and pgrep(1)/pkill(1), which can show all processes running in a system:37
$ ps -ax
PID TT STAT TIME COMMAND
While all processes are visible to each other, they are restricted from interacting with each38
other based on the user that each process is running as. A non-root user can only signal their39
own processes. Attempts to signal processes running as another user fails:40
$ whoami
dlg
$ ps -U _sndio
PID TT STAT TIME COMMAND
47188 ?? I$ kill 47188
ksh: kill: 47188: Operation not permitted
$
Page 2 of 11
COMP3301 Semester 1 2024 Assignment 1
However, the root user is allowed to signal any process:41
$ doas kill 47188
doas (dlg@comp3301.eait.uq.edu.au) password:
$ ps -U _sndio
PID TT STAT TIME COMMAND
$
3 Zones Implementation42
Zones are implemented for this assignment to add further isolation of processes. Processes43
running within a zone can only see and interact with processes running within the same zone,44
regardless of which user within the zone is running the commands. This implementation is45
loosely modelled on the design of Solaris Zones as described in PSARC/2002/174.46
The exception to this enhanced isolation is for processes running in the ”global” zone, which is47
the default zone that is created and exists on boot. Processes running in the global zone can48
see all other processes in the system, including those running in other (non-global) zones, and49
the root user in the global zone can signal any of these processes too. However, non-root users50
in the global zone cannot signal processes in other zones, even if they are running as the same51
user.52
The provided diff implements changes to the kernel and several userland utilities and adds a53
zone(8) command and man page. The zone(8) command provides several sub-commands that54
expose the functionality of the kernel zone subsystem.55
3.1 Provided Zone Syscalls56
zone_create()57
zoneid_t zone_create(const char *zonename);
zone_create() creates a new zone id for use in the system, with a unique name specified by58
zonename.59
zone_destroy()60
int zone_destroy(zoneid_t z);
zone_destroy() deletes the specified zone instance. The zone must have no running processes61
inside it for the request to succeed.62
zone_enter()63
int zone_enter(zoneid_t z);
zone_enter() moves the current process into the specified zone.64
Page 3 of 11
COMP3301 Semester 1 2024 Assignment 1
zone_list()65
int zone_list(zoneid_t *zs, size_t *nzs);
In the global zone zone_list() provides the list of zones in the running system as an array of66
zoneid ts. If run in a non-global zone, the list will only contain the current zone.67
zone_name()68
int zone_name(zoneid_t z, char *name , size_t namelen);
The zone_name() syscall provides the name of the zone identified by the z argument. If run69
in a non-global zone the z id must be the identifier for the current zone. In the global zone it70
can be any zone identifier.71
zone_id()72
1zoneid_t zone_id(const char *name);
zone_id() provides the id associated with the name zone. If run in a non-global zone, only the73
current zone name may be specified. If name is a NULL pointer the zone id calling process is74
running in is returned.75
zone_stats()76
1int zone_stats(zoneid_t z, struct zstats *zstats);
zone_stats() provides an assortment of operating system statistics resulting from processes77
in the zone associated with the id z.78
3.2 zone(8)79
1usage: zone create zonename
2zone destroy zonename
3zone exec zonename command ...
4zone list
5zone id [zonename]
6zone name [zid]
7zone stats [-H] [-o property [ ,...] zone [...]
The zone(8) program uses the zone syscalls to allow systems administrators or operators to80
use the zone subsystem in the kernel.81
zone create82
zone create uses the zone_create() syscall to create a zone with the specified name.83
zone destroy84
zone destroy uses the zone_destroy() syscall to create a zone with the specified name. If a85
zone with the specified name does not exist, zone(8) will attempt to interpret the argument86
as a numeric zone identifier.87
Page 4 of 11
COMP3301 Semester 1 2024 Assignment 1
zone exec88
zone exec uses the zone_enter() syscall to move itself into the specified zone, and then89
executes the program. If a zone with the specified name does not exist, zone(8) will attempt90
to interpret the argument as a numeric zone identifier.91
zone list92
zone list uses the zone_list() syscall to fetch a list of ids for the currently running zones,93
and iterates over it calling the zone_name() syscall to print out the list of zone ids and names.94
zone name / zone id95
zone name and zone id use their associated syscalls zone_name() and zone_id() to return96
the name of a zone given its id, or the id of a zone given its name.97
zone stats98
zone stats uses the zone_stat() syscall to obtain and print out to the user a series of statis-99
tics from processes running in the current zone. See the manual page in zone(8) for more100
information.101
3.3 Your Tasks102
You will be adding additional functionality to a series of zone(8) sub-commands, adding three103
new zone(8) sub-commands, and implementing any necessary changes to the kernel zones104
system to support them.105
Your additional functionality centers around zone permissions. Files have an associated “user”106
and “group”, and this user or group may have permission to operate on the file. Your task is to107
associate zones with a particular owner and group, and allow the owner of the zone and users108
who are in that group to perform operations on the zone (regardless of whether they are the109
owner of the zone).110
In short, where zones are now only controllable by root, your changes will allow the owner of111
a zone and a different group of users to control a zone.112
The additional sub-commands you will be implementing are: zone rename, which will change113
the name of a zone; zone chown, which will change the owner of a zone in a manner similar114
to the existing chown(8); and zone chgrp, which will change the group of a zone in a manner115
similar to the exist chgrp(8).116
4 Instructions117
To complete the assignment, you will need to do the following.118
4.1 Apply the diff119
1- Fetch https://stluc.manta.uqcloud.net/comp3301/public /2024/a1 -zones -base.
patch
2- Create an a1 branch
3- ‘git checkout -b a1 ‘
Page 5 of 11
COMP3301 Semester 1 2024 Assignment 1
4- Apply the base patch to the a1 branch
5- ‘git am /path/to/a1 -zones -base.patch ‘ in /usr/src
6- Build the kernel
7- ‘cd /usr/src/sys/arch/amd64/compile/GENERIC.MP ‘
8- ‘make obj ‘
9- ‘make config ‘
10- ‘make -j 5‘
11- ‘doas make install ‘
12- Reboot into the kernel
13- ‘doas reboot ‘
14- ‘make obj ‘ in /usr/src
15- ‘doas make includes ‘ in /usr/src/include
16- Verify the zones syscalls are in /usr/include/sys/syscall.h
17- Verify /usr/include/sys/zones.h exists
18- Make and install libc
19- ‘cd /usr/src/lib/libc ‘
20- ‘make -j 5‘
21- ‘doas make install ‘
22- Optional: make ps , and pkill/pgrep
23- make zone (8)
24- ‘cd /usr/src/usr.sbin/zone ‘
25- ‘make ‘
26- ‘doas make install ‘
27- Verify ‘zone (8)‘ and the zones subsystem works:
28$ zone list
29ID NAME
300 global
31$ zone create
32usage: zone create zonename
33$ zone create test
34zone: create: Operation not permitted
35$ doas zone create test
36doas (dlg@comp3301.eait.uq.edu.au) password:
37$ zone list
38ID NAME
390 global
4042101 test
41$ zone id
420
43$ zone id test
4442101
45$ zone exec test ps -aux
46zone: enter: Operation not permitted
47$ doas zone exec test ps -aux
48USER PID %CPU %MEM VSZ RSS TT STAT STARTED TIME COMMAND
49root 41705 0.0 0.1 628 580 p0 R+pU/0 3:37PM 0:00.14 ps -aux
50$ doas zone exec test zone id
5142101
52$ doas zone exec test zone id global
53zone: id: No such process
54$
As you add the functionality specified in the next sections, some of these steps will be repeated.120
eg, changing the kernel means rebuilding and installing the kernel. Adding a syscall means121
making the syscall stub as a function visible in the headers (make includes), and callable122
through libc.123
Page 6 of 11
COMP3301 Semester 1 2024 Assignment 1
A note on errors124
We have over-specified the errors you should return from your syscalls - if you do not require an125
error code (for example, never returning ENOMEM on memory failures because you never allocate126
any memory) then you do not have to use it. The reverse is also true - if you find an error case127
that is not listed, choose an appropriate error from errno(2). We will not explicitly test all128
errors, but during your code interview, we will expect you to be able to explain the suitability129
of the error codes you use.130
4.2 Zone Rename131
The zone(8) commands should be extended to enable renaming of zones. Zones should only132
be able to be renamed by the owner, root, or members of the zone’s group. Additionally, the133
global zone cannot be renamed, and zone names must be unique.134
1$ zone
2usage: zone create zonename
3zone destroy zonename
4zone exec zonename command ...
5zone list
6zone name [id]
7zone id [zonename]
8zone rename id name
9$ doas zone create foo
10$ zone list
11ID NAME
120 global
13289 foo
14$ doas zone rename 298 bar
15$ zone list
16ID NAME
170 global
18289 bar
19$ doas zone rename 0 something
20zone: name: Permission denied
21$ doas zone rename 289 global
22zone: name: File exists
4.3 Modifications to Existing Syscalls135
zone_create() syscall136
The zone_create() syscall should now ensure that the created zone is associated with the137
group of the user that created it, as well as the user themself. Additionally, this will mean138
ensuring that non-root users can create zones.139
All other syscalls140
The full suite of zone_* syscalls should permit users with matching credentials to perform zone141
operations on them, not only the owner and the root user.142
Page 7 of 11
COMP3301 Semester 1 2024 Assignment 1
4.4 Zone name and zone list143
zone_name() syscall144
The zone_name() syscall should be renamed to zone_info(). Subsequently, it should return145
not only the name and namelen, but a struct, containing the id of the user and the id of the146
group that has permission to control the zone. The zone(8) userland sub-command for zone147
name should also be modified in line with these changes - the name should be changed to zone148
info and the additional information should be provided to the user.149
zone list150
The zone list subcommand should now take flags: -o and -g. If either of these flags are151
provided, the owner and the group that have control over the zones should also be printed, in152
table format.153
4.5 Zone chown and chgrp154
The zone(8) commands and the kernel zones system should be extended to enable changing155
the owner and group of a zone. Zone owners and groups should only be able to be changed by156
the owner, root, or members of the zone’s group. Additionally, the owner of the global zone157
cannot be changed.158
1$ zone
2usage: zone create zonename
3zone destroy zonename
4zone exec zonename command ...
5zone list
6zone name [id]
7zone id [zonename]
8zone chown [id]
9zone chgrp [id]
To support these subcommands, you will need to implement the following system calls:159
zone_chown() syscall160
int zone_chown(zoneid_t z, uid_t user);
The zone_chown() syscall alters the owner of the zone identified by the z argument. The new161
owner should be the owner identified by the user argument. If called from a non-global zone162
then the z id must be the identifier for the current zone, but in the global zone it can be any163
zone identifier.164
Potential Errors:165
 EPERM - the user does not have permission to alter the zone z166
 ESRCH - the zone identified by z does not exist167
 ENOMEM - the system was not able to allocate memory168
 EINVAL - the zone to alter was the global zone169
Page 8 of 11
COMP3301 Semester 1 2024 Assignment 1
zone_chgrp() syscall170
int zone_chgrp(zoneid_t z, gid_t group);
The zone_chgrp() syscall alters the owner of the zone identified by the z argument. The new171
owner should be the group identified by the group argument. If called from a non-global zone172
then the z id must be the identifier for the current zone, but in the global zone it can be any173
zone identifier.174
Potential Errors:175
 EPERM - the user does not have permission to alter the zone z176
ESRCH - the zone identified by z does not exist177
 ENOMEM - the system was not able to allocate memory178
 EINVAL - the zone to alter was the global zone179
5 Other Requirements & Suggestions180
5.1 Code Style181
Your code is to be written according to OpenBSD’s style guide, as per the ‘style(9)‘ man page.182
An automatic tool for checking for style violations is available at uqcloud.net/comp3301/public/2022/cstyle.pl>. This tool will be used to calculate your184
style marks for this assignment.185
5.2 Compilation186
Your code for this assignment is to be built on an amd64 OpenBSD 7.5 system identical to your187
course-provided VM.188
189
The following steps must succeed:190
 make obj; make config; make in src/sys/arch/amd64/compile/GENERIC.MP191
 make obj; make includes in src192
 make obj; make; make install in src/lib/libc193
 make obj; make; make install in src/usr.sbin/zone194
The existing Makefiles in the provided code are functional as-is, but may need modification195
as part of your work for this assignment. Note that the existing Makefile ensures the -Wall196
flag is passed to the compiler, as well as a few other warning and error-related flags.197
Page 9 of 11
COMP3301 Semester 1 2024 Assignment 1
5.3 Provided code198
The provided code which forms the basis for this assignment can be downloaded as a single199
patch file at:200
https://stluc.manta.uqcloud.net/comp3301/public/2024/a1-zones-base.patch201
202
You should create a new a1 branch in your repository based on the openbsd-7.5 tag using git203
checkout, and then apply this base patch using the git am command:204
1$ git checkout -b a1 openbsd -7.5
2$ ftp https://stluc.manta.uqcloud.net/comp3301/public /2024/a1 -zones -base.
patch
3$ git am < a1 -zones -base.patch
4$ git push origin a1
5.4 Recommendations205
The following order will likely be the most reasonable way to complete this assignment:206
1. Download, build, and install the zones patch.207
2. Add the zone rename subcommand to zone(8).208
3. Minimally modify zone_create() to store credentials.209
4. Rewrite zone_name() to zone_info().210
This ensures you have a way to view the credentials of a zone.211
5. Add the zone_chown() and zone_chgrp() syscalls.212
6. Add the corresponding zone chown and zone chgrp commands to zone(8).213
7. Fix up any tiny bugs and ensure it’s all working. But you did that as you were going... right?214
Additionally, it is strongly recommended (and in some cases, required) that the following APIs215
be considered for use as part of your changes:216
? ucred(9) - provides necessary handlers for dealing with user and group credentials217
? copyin(9)/copyout(9) - provides the ability to copy data across the userspace boundary218
? user_from_uid(3) - conversions from group/user name to id and back219
? strtonum(3) - BSD style safe string to int conversions220
? Finally, you may wish to look at the header file sys/proc.h to see how user and group221
credentials are currently stored by threads.222
Page 10 of 11
COMP3301 Semester 1 2024 Assignment 1
6 Reflection223
Provide a reflection on your implementation by briefly answering the following questions:224
1. Describe the steps you took or draw a flowchart.225
2. Describe an error that you encountered.226
3. Describe how the error was debugged.227
4. Describe how the bug was solved.228
Upload both pdf and your answers it as a pdf to the Blackboard a1 reflection submission. Page229
length is a maximum 2 pages or less. Pdf name must be your STUDENT NUMBER -230
a1.pdf. Note this is your XXXXXXXX ID number and not sXXXXXXX login.231
7 Submission232
Submission must be made electronically by committing to your Git repository on ‘source.eait.uq.edu.au‘.233
In order to mark your assignment the markers will check out the ‘a1‘ branch from your reposi-234
tory. Code checked into any other branch in your repository will not be marked.235
236
As per the ‘source.eait.uq.edu.au‘ usage guidelines, you should only commit source code and237
Makefiles.238
239
Your ‘a1‘ branch should consist of:240
? The openbsd-7.5 base commit241
? The A1 base patch commit242
? Commit(s) for adding the required functionality243
7.1 Marking244
Your submission will be marked by course tutors and staff, during an in-person demo with you,245
at your lab session during the due week. You must attend your session, in-person, otherwise246
your submission will not be marked. Online attendence, e.g. zoom, is not permitted.247