Skip to content

Commit c048da9

Browse files
gornjasgornjas
committed
Add an interim userland utility for managing vimages / virtualized
network stack infrastructure. Requested by: julian (mentor) Approved by: julian (mentor)
1 parent 403f4aa commit c048da9

File tree

4 files changed

+347
-0
lines changed

4 files changed

+347
-0
lines changed

‎tools/tools/README‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ sysdoc Build a manual page with available sysctls for a specific
6161
kernel configuration.
6262
tinybsd Script to build FreeBSD embedded systems.
6363
track Track the progress of a world / kernel build
64+
vimage An interim utility for managing the virtualized network
65+
stack infrastructure.
6466
vop_table Generates a HTML document that shows all the VOP's in
6567
the kernel.
6668
whereintheworld Summarizes "make world" output.

‎tools/tools/vimage/Makefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# $FreeBSD$
2+
3+
PROG= vimage
4+
5+
WARNS?= 2
6+
CFLAGS+= -I../../../sys
7+
8+
MAN= vimage.8
9+
10+
BINDIR?= /usr/sbin
11+
NO_SHARED?= YES
12+
13+
.include <bsd.prog.mk>

‎tools/tools/vimage/vimage.8‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
.\" Copyright (c) 2002, 2003 Marko Zec <[email protected]>
2+
.\" Copyright (c) 2009 University of Zagreb
3+
.\" Copyright (c) 2009 FreeBSD Foundation
4+
.\"
5+
.\" All rights reserved.
6+
.\"
7+
.\" Redistribution and use in source and binary forms, with or without
8+
.\" modification, are permitted provided that the following conditions
9+
.\" are met:
10+
.\" 1. Redistributions of source code must retain the above copyright
11+
.\" notice, this list of conditions and the following disclaimer.
12+
.\" 2. Redistributions in binary form must reproduce the above copyright
13+
.\" notice, this list of conditions and the following disclaimer in the
14+
.\" documentation and/or other materials provided with the distribution.
15+
.\"
16+
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17+
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20+
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21+
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22+
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23+
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24+
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25+
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26+
.\" SUCH DAMAGE.
27+
.\"
28+
.\" $FreeBSD$
29+
.\"
30+
.Dd June 6, 2009
31+
.Dt VIMAGE 8
32+
.Os
33+
.Sh NAME
34+
.Nm vimage
35+
.Nd manage virtual network stacks
36+
.Sh SYNOPSIS
37+
.Nm
38+
.Ar vi_name
39+
.Op command
40+
.Nm
41+
.Fl c
42+
.Ar vi_name
43+
.Nm
44+
.Fl d
45+
.Ar vi_name
46+
.Nm
47+
.Fl l
48+
.Op Ar vi_name
49+
.Nm
50+
.Fl i
51+
.Ar vi_name interface
52+
.Sh DESCRIPTION
53+
.Nm
54+
command is an interm user interface for controlling the virtual network
55+
stacks in FreeBSD.
56+
.Ss Overview
57+
A virtual image reprepresents an isolated operating environment with its
58+
own independent network stack instance. Every process, socket and network
59+
interface present in the system is always attached to one, and only one,
60+
virtual image i.e. virtual network stack instance.
61+
During the system bootup sequence default virtual image is created to
62+
which all the configured interfaces and user processes are initially
63+
assigned.
64+
Assuming that enough system resources and per virtual image privileges
65+
are provided, the super-user can create and manage a hierarchy of
66+
subordinated virtual images. The
67+
.Nm
68+
command allows for creation, deletion and monitoring of virtual images,
69+
as well as for execution of arbitrary processes in a targeted virtual
70+
image.
71+
.Ss Invocation
72+
If invoked with no modifiers, the
73+
.Nm
74+
command spawns a new shell process in virtual image
75+
.Ar vi_name .
76+
If provided, the optional arguments following the virtual image name
77+
.Ar vi_name
78+
are interpreted as a standard command line issued at a shell,
79+
otherwise an interactive shell is started in the target virtual image.
80+
.Pp
81+
The following parameters are available:
82+
.Bl -tag -width indent
83+
.It Fl c
84+
Create a new virtual image named
85+
.So
86+
.Ar vi_name
87+
.Sc .
88+
.It Fl d
89+
Delete the virtual image
90+
.Ar vi_name .
91+
No processes and/or sockets should exist in the target virtual image
92+
in order for the delete request to succeed. Non-loopback interfaces
93+
residing in the target virtual image will be reassigned to the virtual
94+
image's parent.
95+
.It Fl l
96+
List the properties and statistics for virtual images one level
97+
below the current one in the hierarchy. If an optional argument
98+
.Ar vi_name
99+
is provided, only the information regarding the target virtual image
100+
.Ar vi_name
101+
is displayed.
102+
.It Fl lr
103+
List the properties and statistics for all virtual images in
104+
the hierarchy of subordinated vimages. If an optional argument
105+
.Ar vi_name
106+
is provided, the hierarchy will be traversed at and below the
107+
.Ar vi_name
108+
level.
109+
.It Fl i
110+
Move the interface
111+
.Ar interface
112+
to the target virtual image
113+
.Ar vi_name .
114+
If the value of
115+
.Ar vi_name
116+
argument is
117+
.So ..
118+
.Sc ,
119+
the interface is returned to the parent of the current virtual image.
120+
.El
121+
.Sh EXAMPLES
122+
Create a new virtual image named
123+
.So v1
124+
.Sc :
125+
.Pp
126+
.Dl vimage -c v1
127+
.Pp
128+
Execute the
129+
.So ifconfig
130+
.Sc command in the virtual image
131+
.So v1
132+
.Sc :
133+
.Pp
134+
.Dl vimage v1 ifconfig
135+
.Pp
136+
Move the interface
137+
.So vlan0
138+
.Sc to the virtual image
139+
.So v1
140+
.Sc :
141+
.Pp
142+
.Dl vimage -i v1 vlan0
143+
.Pp
144+
Show the status information for virtual image
145+
.So v1
146+
.Sc :
147+
.Pp
148+
.Dl vimage -l v1
149+
.Sh DIAGNOSTICS
150+
The
151+
.Nm
152+
command exits 0 on success, and >0 if an error occurs.
153+
.Sh SEE ALSO
154+
.Xr jail 8
155+
.Sh BUGS
156+
If memory allocation failure occurs during the vimage creation, it will remain
157+
undetected/ignored in the current implementation, thus latently scheduling
158+
an almost imminent system crash in the future.
159+
.Sh AUTHOR
160+
.An "Marko Zec" Aq [email protected]
161+
.Sh HISTORY
162+
The
163+
.Nm
164+
facility first appeared as a patch against FreeBSD 4.7-RELEASE in 2002.

‎tools/tools/vimage/vimage.c‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
/*
2+
* Copyright (c) 2002-2004 Marko Zec <[email protected]>
3+
* Copyright (c) 2009 University of Zagreb
4+
* Copyright (c) 2009 FreeBSD Foundation
5+
*
6+
* Redistribution and use in source and binary forms, with or without
7+
* modification, are permitted provided that the following conditions
8+
* are met:
9+
* 1. Redistributions of source code must retain the above copyright
10+
* notice, this list of conditions and the following disclaimer.
11+
* 2. Redistributions in binary form must reproduce the above copyright
12+
* notice, this list of conditions and the following disclaimer in the
13+
* documentation and/or other materials provided with the distribution.
14+
*
15+
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16+
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18+
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19+
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20+
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21+
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22+
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23+
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24+
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25+
* SUCH DAMAGE.
26+
*
27+
* $FreeBSD$
28+
*/
29+
30+
#include <sys/types.h>
31+
#include <sys/ioctl.h>
32+
#include <sys/socket.h>
33+
#include <sys/vimage.h>
34+
35+
#include <errno.h>
36+
#include <stdio.h>
37+
#include <stdlib.h>
38+
#include <string.h>
39+
#include <unistd.h>
40+
41+
void
42+
vi_print(struct vi_req *vi_req)
43+
{
44+
45+
printf("\"%s\":\n", vi_req->vi_name);
46+
printf(" %d sockets, %d ifnets, %d processes\n",
47+
vi_req->vi_sock_count, vi_req->vi_if_count, vi_req->vi_proc_count);
48+
}
49+
50+
int
51+
main(int argc, char **argv)
52+
{
53+
int s;
54+
char *shell;
55+
int cmd = VI_SWITCHTO;
56+
struct vi_req vi_req;
57+
58+
s = socket(AF_INET, SOCK_DGRAM, 0);
59+
if (s == -1)
60+
goto abort;
61+
62+
bzero(&vi_req, sizeof(vi_req));
63+
strcpy(vi_req.vi_name, "."); /* . = this vimage. */
64+
65+
if (argc == 1)
66+
cmd = VI_GET;
67+
68+
if (argc == 2 && strcmp(argv[1], "-l") == 0)
69+
cmd = VI_GETNEXT;
70+
71+
if (argc == 2 && strcmp(argv[1], "-lr") == 0)
72+
cmd = VI_GETNEXT_RECURSE;
73+
74+
if (argc == 3) {
75+
strcpy(vi_req.vi_name, argv[2]);
76+
if (strcmp(argv[1], "-l") == 0)
77+
cmd = VI_GET;
78+
if (strcmp(argv[1], "-c") == 0)
79+
cmd = VI_CREATE;
80+
if (strcmp(argv[1], "-d") == 0)
81+
cmd = VI_DESTROY;
82+
}
83+
84+
if (argc >= 3) {
85+
strcpy(vi_req.vi_name, argv[2]);
86+
if (strcmp(argv[1], "-c") == 0)
87+
cmd = VI_CREATE;
88+
if (strcmp(argv[1], "-i") == 0)
89+
cmd = VI_IFACE;
90+
}
91+
92+
vi_req.vi_api_cookie = VI_API_COOKIE;
93+
vi_req.vi_req_action = cmd;
94+
switch (cmd) {
95+
96+
case VI_GET:
97+
if (ioctl(s, SIOCGPVIMAGE, (caddr_t)&vi_req) < 0)
98+
goto abort;
99+
if (argc == 1)
100+
printf("%s\n", vi_req.vi_name);
101+
else
102+
vi_print(&vi_req);
103+
exit(0);
104+
105+
case VI_GETNEXT:
106+
case VI_GETNEXT_RECURSE:
107+
vi_req.vi_req_action = VI_GET;
108+
if (ioctl(s, SIOCGPVIMAGE, (caddr_t)&vi_req) < 0)
109+
goto abort;
110+
vi_print(&vi_req);
111+
vi_req.vi_req_action = VI_GETNEXT_RECURSE;
112+
while (ioctl(s, SIOCGPVIMAGE, (caddr_t)&vi_req) == 0) {
113+
vi_print(&vi_req);
114+
vi_req.vi_req_action = cmd;
115+
}
116+
exit(0);
117+
118+
case VI_IFACE:
119+
strncpy(vi_req.vi_if_xname, argv[3],
120+
sizeof(vi_req.vi_if_xname));
121+
if (ioctl(s, SIOCSIFVIMAGE, (caddr_t)&vi_req) < 0)
122+
goto abort;
123+
printf("%s@%s\n", vi_req.vi_if_xname, vi_req.vi_name);
124+
exit(0);
125+
126+
case VI_CREATE:
127+
if (ioctl(s, SIOCSPVIMAGE, (caddr_t)&vi_req) < 0)
128+
goto abort;
129+
exit(0);
130+
131+
case VI_SWITCHTO:
132+
strcpy(vi_req.vi_name, argv[1]);
133+
if (ioctl(s, SIOCSPVIMAGE, (caddr_t)&vi_req) < 0)
134+
goto abort;
135+
136+
vi_req.vi_req_action = VI_GET;
137+
strcpy(vi_req.vi_name, ".");
138+
if (ioctl(s, SIOCGPVIMAGE, (caddr_t)&vi_req) < 0) {
139+
printf("XXX this should have not happened!\n");
140+
goto abort;
141+
}
142+
close(s);
143+
144+
if (argc == 2) {
145+
printf("Switched to vimage %s\n", argv[1]);
146+
if ((shell = getenv("SHELL")) == NULL)
147+
execlp("/bin/sh", argv[0], NULL);
148+
else
149+
execlp(shell, argv[0], NULL);
150+
} else
151+
execvp(argv[2], &argv[2]);
152+
break;
153+
154+
case VI_DESTROY:
155+
if (ioctl(s, SIOCSPVIMAGE, (caddr_t)&vi_req) < 0)
156+
goto abort;
157+
exit(0);
158+
159+
default:
160+
fprintf(stderr, "usage: %s [-cdilr] vi_name [args]\n",
161+
argv[0]);
162+
exit(1);
163+
}
164+
165+
abort:
166+
perror("Error");
167+
exit(1);
168+
}

0 commit comments

Comments
 (0)