-
Notifications
You must be signed in to change notification settings - Fork 41
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add FreeBSD Jail execution environment support #224
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -10,3 +10,4 @@ | |
|
||
* The FreeBSD Foundation | ||
* Google Inc. | ||
* Igor Ostapenko <pm@igoro.pro> |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,4 +1,4 @@ | ||||||
.\" Copyright 2012 The Kyua Authors. | ||||||
.\" Copyright 2012-2024 The Kyua Authors. | ||||||
.\" All rights reserved. | ||||||
.\" | ||||||
.\" Redistribution and use in source and binary forms, with or without | ||||||
|
@@ -25,7 +25,7 @@ | |||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||||||
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||||||
.Dd July 3, 2015 | ||||||
.Dd March 23, 2024 | ||||||
.Dt KYUAFILE 5 | ||||||
.Os | ||||||
.Sh NAME | ||||||
|
@@ -173,6 +173,75 @@ Refer to the | |||||
section below for clarification. | ||||||
.It Va description | ||||||
Textual description of the test. | ||||||
.It Va execenv | ||||||
The name of the execution environment to be used for running the test. | ||||||
If empty or not defined, the | ||||||
.Sq host | ||||||
execution environment is meant. | ||||||
The possible values are: | ||||||
.Bl -tag -width xUnnnnnnn | ||||||
.It host | ||||||
The default environment which runs the test as a usual child process. | ||||||
.It jail | ||||||
The | ||||||
.Fx | ||||||
.Xr jail 8 | ||||||
environment. | ||||||
It creates a temporary jail to run the test and its optional cleanup logic | ||||||
within. | ||||||
.Pp | ||||||
This feature requires | ||||||
.Xr kyua 1 | ||||||
to be running with superuser privileges. | ||||||
.Pp | ||||||
The difference between | ||||||
.Va security.jail.children.max | ||||||
and | ||||||
.Va security.jail.children.cur | ||||||
sysctl of the jail | ||||||
.Xr kyua 1 | ||||||
is running within must have a value high enough for the jail based tests | ||||||
planned to be run. | ||||||
For instance, the value 1 should be enough for a sequential run of simple | ||||||
tests. | ||||||
Otherwise, such aspects as parallel test execution and sub-jails spawned | ||||||
by specific test cases should be considered. | ||||||
.Pp | ||||||
The formula of a temporary jail name is | ||||||
.Sq kyua | ||||||
+ | ||||||
.Va test program path | ||||||
+ | ||||||
.Sq _ | ||||||
+ | ||||||
.Va test case name . | ||||||
All non-alphanumeric characters are replaced with | ||||||
.Sq _ . | ||||||
.Sq kyua_usr_tests_sys_netpfil_pf_pass_block_v4 | ||||||
is an example for /usr/tests/sys/netpfil/pf/pass_block:v4 test case. | ||||||
.El | ||||||
.It Va execenv_jail_params | ||||||
Additional test-specific whitespace-separated parameters of | ||||||
.Fx | ||||||
.Xr jail 8 | ||||||
to create a temporary jail within which the test is run. | ||||||
It makes sense only if execenv is set to | ||||||
.Sq jail . | ||||||
.sp | ||||||
.Xr kyua 1 | ||||||
implicitly passes | ||||||
.Sq children.max | ||||||
parameter to | ||||||
.Xr jail 8 | ||||||
for a temporary jail with the maximum possible value according to | ||||||
the jail | ||||||
.Xr kyua 1 | ||||||
itself is running within. | ||||||
It allows tests to easily spawn their own sub-jails without additional | ||||||
configuration. | ||||||
It can be overridden via | ||||||
.Va execenv_jail_params | ||||||
if needed. | ||||||
.It Va is_exclusive | ||||||
If true, indicates that this test program cannot be executed along any other | ||||||
programs at the same time. | ||||||
|
@@ -360,6 +429,36 @@ test_suite('FreeBSD') | |||||
plain_test_program{name='the_test', | ||||||
['custom.FreeBSD-Bug-Id']='category/12345'} | ||||||
.Ed | ||||||
.Ss FreeBSD jail execution environment | ||||||
The following example configures the test to be run within a temporary jail | ||||||
with | ||||||
.Xr vnet 9 | ||||||
support and the permission to create raw sockets: | ||||||
.Bd -literal -offset indent | ||||||
syntax(2) | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. (picking the first instance)
Suggested change
This allows the engine to treat function in a backwards compatible manner with the older Kyuafiles by not dealing with the execenv related syntax. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for opening this topic. I was thinking about this, but I decided not to make a move and postpone its discussion due to lack of strong opinions on my side. In terms of "syntax" term it's not changed, only extra metadata can be defined (if we think about metadata as a free set of key-value), but, probably, the project's philosophy/design means any change should bump the version -- this is where long term maintainer's opinion is expected. Also, I've found no direct support of versioning in the code, i.e. older Kyua binary simply stops a Kyuafile processing and errors about "unknown property". Conversely, if Kyuafile's I guess we could discuss and conclude here on the desired direction for the project but implement it as a separate PR if it requires extra changes. What do you think? |
||||||
|
||||||
test_suite('FreeBSD') | ||||||
|
||||||
atf_test_program{name='network_test', | ||||||
execenv='jail', | ||||||
execenv_jail_params='vnet allow.raw_sockets', | ||||||
required_user='root'} | ||||||
.Ed | ||||||
.Pp | ||||||
A test case itself may have no requirements in superuser privileges, | ||||||
but required_user='root' metadata property reminds that the jail execution | ||||||
environment requires | ||||||
.Xr kyua 1 | ||||||
being running with root privileges, and the test is skipped otherwise with | ||||||
the respective message. The combination of | ||||||
.Va execenv | ||||||
set to | ||||||
.Sq jail | ||||||
and | ||||||
.Va required_user | ||||||
set to | ||||||
.Sq unprivileged | ||||||
does not work respectively. | ||||||
.Ss Connecting disjoint test suites | ||||||
Now suppose you had various test suites on your file system and you would | ||||||
like to connect them together so that they could be executed and treated as | ||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mentioning what execenv's are supported would be a good idea -- otherwise it's unclear (without looking at the source code) what is or isn't supported.
Referencing alternative documentation is a good thing to do in place of hardcoding the values, but I think being explicit avoids the need for the documentation potentially becoming out of sync/less implicit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's already covered in
![Screenshot 2024-05-07 at 3 13 38 PM](https://private-user-images.githubusercontent.com/9573190/328516743-f57cc787-4e06-483d-826c-8c3915a702a8.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MTk1MzY4MTYsIm5iZiI6MTcxOTUzNjUxNiwicGF0aCI6Ii85NTczMTkwLzMyODUxNjc0My1mNTdjYzc4Ny00ZTA2LTQ4M2QtODI2Yy04YzM5MTVhNzAyYTgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDYyOCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA2MjhUMDEwMTU2WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZWI2NDhlNWVmYWZhOGVlZWU2YzQwMTFkZTBjZjE2MmJiYTNlZmU2ZTNjYTQ5MWJhYmI5M2JlMjYxN2JjNTAwYyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.BTjCTvzFv1fiStTWJ9pOKQpoBvm2sab6D_z1TG7KXsA)
kyuafile.5
: https://github.com/ihoro/kyua/blob/9721be7abbd48f2ee020e5deaee1e1daa44c0087/doc/kyuafile.5.in#L181I guess we could simply make a reference to the
kyuafile.5
for the possible values.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added the mentioned reference.