Skip to content
This repository was archived by the owner on Oct 25, 2020. It is now read-only.

Commit b8fb9da

Browse files
rd235rd235
committed
man and descriptions added
1 parent 73bb5f8 commit b8fb9da

File tree

7 files changed

+264
-32
lines changed

7 files changed

+264
-32
lines changed

‎README.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,55 @@
11
# libslirp
22
A TCP-IP emulator as a library.
3+
4+
## Slirp
5+
6+
Originally designed to provide PPP/SLIP over terminal lines, slirp is a general purpose TCP-IP emulator widely used
7+
by virtual machine hypervisor to provide virtual networking services.
8+
9+
Qemu, virtualbox, user-mode linux include slirp to provide the guest os with a virtual network while requiring no
10+
configuration nor privileged services on the host.
11+
12+
This project wraps the slirp code in a library featuring a clean and simple interface.
13+
14+
## libslirp tutorial
15+
16+
The first operation to use a slirp virtual network is <code>slirp_open</code>.
17+
<pre>
18+
SLIRP *myslirp = slirp_open(SLIRP_IPV4 | SLIRP_IPV6);
19+
</pre>
20+
21+
*myslirp* is the descriptor of the slirp network.
22+
23+
The library has been designed to assign suitable default values for all the parameters:
24+
* default route: 10.0.2.2/24
25+
* DNS forward: 10.0.2.3
26+
* DHCP addresses: 10.0.2.15 - 10.0.2.31
27+
* default route ipv6: fe80::2/64
28+
* DNS forward IPv6: fe80::3
29+
* Virtual Router Advertisement daemon: active.
30+
31+
Libslirp provides functions to override the values (see <code>man libslirpcfg</code>).
32+
33+
After the (eventual) configuration of all the parameters the slirp networj can be activated:
34+
<pre>
35+
slirp_start(myslirp);
36+
</pre>
37+
38+
Now virtual networking (ethernet) packets can be sent and received using *slirp_send* and *slirp_recv*. e.g.:
39+
<pre>
40+
sentlen = slirp_send(myslirp, pkt, pktlen);
41+
pktlen = slirp_recv(myslirp, buf, buflen);
42+
</pre>
43+
44+
*slirp_fd* returns a file descriptor which can be used to wait for incoming packets using poll or select.
45+
<pre>
46+
myslirpfd = slirp_fd(myslirp);
47+
</pre>
48+
49+
It is also possible to set up port forwarding for TCP, UDP (currently IPV4 only) or connect X-window clients
50+
running in the virtual network to a X server UNIX socket, see <code>man libslirpfwd</code>.
51+
52+
To terminate the slirp network, call:
53+
<pre>
54+
slirp_close(myslirp)
55+
</pre>

‎man/Makefile.am

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
man_MANS = libslirp.3
1+
man_MANS = libslirp.3 libslirpfwd.3 libslirpcfg.3
22

33
install-data-hook:
44
ln -sf libslirp.3 $(DESTDIR)$(man3dir)/slirp_open.3
@@ -7,6 +7,21 @@ install-data-hook:
77
ln -sf libslirp.3 $(DESTDIR)$(man3dir)/slirp_recv.3
88
ln -sf libslirp.3 $(DESTDIR)$(man3dir)/slirp_fd.3
99
ln -sf libslirp.3 $(DESTDIR)$(man3dir)/slirp_close.3
10+
ln -sf libslirpfwd.3 $(DESTDIR)$(man3dir)/slirp_add_fwd.3
11+
ln -sf libslirpfwd.3 $(DESTDIR)$(man3dir)/slirp_remove_fwd.3
12+
ln -sf libslirpfwd.3 $(DESTDIR)$(man3dir)/slirp_add_unixfwd.3
13+
ln -sf libslirpfwd.3 $(DESTDIR)$(man3dir)/slirp_remove_unixfwd.3
14+
ln -sf libslirpfwd.3 $(DESTDIR)$(man3dir)/slirp_add_cmdexec.3
15+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_addr.3
16+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_addr6.3
17+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_hostname.3
18+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_tftppath.3
19+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_bootfile.3
20+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_dhcp.3
21+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_dnsaddr.3
22+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_dnsaddr6.3
23+
ln -sf libslirpcfg.3 $(DESTDIR)$(man3dir)/slirp_set_vdnssearch.3
24+
1025

1126
uninstall-hook:
1227
rm -f $(DESTDIR)$(man3dir)/slirp_open.3
@@ -15,3 +30,16 @@ uninstall-hook:
1530
rm -f $(DESTDIR)$(man3dir)/slirp_recv.3
1631
rm -f $(DESTDIR)$(man3dir)/slirp_fd.3
1732
rm -f $(DESTDIR)$(man3dir)/slirp_close.3
33+
rm -f $(DESTDIR)$(man3dir)/slirp_add_fwd.3
34+
rm -f $(DESTDIR)$(man3dir)/slirp_remove_fwd.3
35+
rm -f $(DESTDIR)$(man3dir)/slirp_add_unixfwd.3
36+
rm -f $(DESTDIR)$(man3dir)/slirp_remove_unixfwd.3
37+
rm -f $(DESTDIR)$(man3dir)/slirp_add_cmdexec.3
38+
rm -f $(DESTDIR)$(man3dir)/slirp_set_addr.3
39+
rm -f $(DESTDIR)$(man3dir)/slirp_set_addr6.3
40+
rm -f $(DESTDIR)$(man3dir)/slirp_set_hostname.3
41+
rm -f $(DESTDIR)$(man3dir)/slirp_set_tftppath.3
42+
rm -f $(DESTDIR)$(man3dir)/slirp_set_bootfile.3
43+
rm -f $(DESTDIR)$(man3dir)/slirp_set_dhcp.3
44+
rm -f $(DESTDIR)$(man3dir)/slirp_set_dnsaddr.3
45+
rm -f $(DESTDIR)$(man3dir)/slirp_set_dnsaddr6.3

‎man/libslirp.3

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
.\"* libslirp: slirp as a library
22
.\" Copyright (C) 2014 Renzo Davoli. University of Bologna. <renzo@cs.unibo.it>
3-
.\"
3+
.\"
44
.\" This library is free software; you can redistribute it and/or
55
.\" modify it under the terms of the GNU Lesser General Public
66
.\" License as published by the Free Software Foundation; either
77
.\" version 2.1 of the License, or (at your option) any later version.
8-
.\"
8+
.\"
99
.\" This library is distributed in the hope that it will be useful,
1010
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
1111
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1212
.\" Lesser General Public License for more details.
13-
.\"
13+
.\"
1414
.\" You should have received a copy of the GNU Lesser General Public
1515
.\" License along with this library; if not, write to the Free Software
1616
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
@@ -51,9 +51,9 @@ SLIRP_RESTRICTED: restrict the netwrk virtualisation to the host only.
5151
.PP
5252
If flags is zero, slirp emulates IPv4 and it is not restricted.
5353

54-
Libslirp standard configuration is:
54+
Libslirp standard configuration is:
5555
.IP \(bu 2
56-
default route: 10.0.2.2
56+
default route: 10.0.2.2
5757
.br
5858
.IP \(bu 2
5959
DNS forward: 10.0.2.3
@@ -76,12 +76,14 @@ Virtual Router Advertisement daemon: active.
7676
\fBslirp_send\fR and \fBslirp_recv\fR return the number of bytes sent or received, -1 in case of error.
7777
\fBslirp_fd\fR returns a valid file descriptor which can be used to wait for incoming packets (using select or poll).
7878
\fBslirp_start\fR and \fBslirp_close\fR return zero, -1 in case of error.
79-
In case of failure, errno is set to indicate the type of error.
79+
In case of failure, errno is set to indicate the type of error.
8080

8181
.SH SEE ALSO
82+
libslirpfwd(3),
83+
libslirpcfg(3)
8284
.SH BUGS
8385
Bug reports should be addressed to <info@virtualsquare.org>
8486
.SH AUTHOR
85-
Renzo Davoli <renzo@cs.unibo.it>: the idea of slirp is by Danny
87+
Renzo Davoli <renzo@cs.unibo.it>: the idea of slirp is by Danny
8688
Gasparovski. This implementation of slirp has been forked from Qemu.
8789
Please refer to the LICENSE file in the source tree main directory for information about the license.

‎man/libslirpcfg.3

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.\"* libslirp: slirp as a library
2+
.\" Copyright (C) 2014 Renzo Davoli. University of Bologna. <renzo@cs.unibo.it>
3+
.\"
4+
.\" This library is free software; you can redistribute it and/or
5+
.\" modify it under the terms of the GNU Lesser General Public
6+
.\" License as published by the Free Software Foundation; either
7+
.\" version 2.1 of the License, or (at your option) any later version.
8+
.\"
9+
.\" This library is distributed in the hope that it will be useful,
10+
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11+
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12+
.\" Lesser General Public License for more details.
13+
.\"
14+
.\" You should have received a copy of the GNU Lesser General Public
15+
.\" License along with this library; if not, write to the Free Software
16+
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17+
18+
.TH libslirpcfg 3 2016-11-16 "VirtualSquare" "Linux Programmer's Manual"
19+
.SH NAME
20+
slirp_set_addr, slirp_set_addr6, slirp_set_hostname, slirp_set_tftppath, slirp_set_bootfile,
21+
slirp_set_dhcp, slirp_set_dnsaddr, slirp_set_dnsaddr6, slirp_set_vdnssearch
22+
.SH SYNOPSIS
23+
.B #include <libslirp.h>
24+
.br
25+
.BI "int slirp_set_addr(SLIRP *slirp, struct in_addr vhost, int prefix);
26+
.br
27+
.BI "int slirp_set_addr6(SLIRP *slirp, struct in6_addr vhost6, int prefix);
28+
.br
29+
.BI "int slirp_set_hostname(SLIRP *slirp, const char *vhostname);
30+
.br
31+
.BI "int slirp_set_tftppath(SLIRP *slirp, const char *tftp_path);
32+
.br
33+
.BI "int slirp_set_bootfile(SLIRP *slirp, const char *bootfile);
34+
.br
35+
.BI "int slirp_set_dhcp(SLIRP *slirp, struct in_addr vdhcp_start);
36+
.br
37+
.BI "int slirp_set_dnsaddr(SLIRP *slirp, struct in_addr vnameserver);
38+
.br
39+
.BI "int slirp_set_dnsaddr6(SLIRP *slirp, struct in6_addr vnameserver6);
40+
.br
41+
.BI "int slirp_set_vdnssearch(SLIRP *slirp, char **vdnssearch);
42+
43+
These functions are provided by libslirp. Link with \fI-lslirp\fR.
44+
.SH DESCRIPTION
45+
Slirp, see liblirp(3), is a TCP/IP emulator. Slirp generates a virtual network using standard user privileges (no need for root access
46+
of CAP_NET_ADMIN).
47+
These functions configure various parameters of slirp (overriding the default values)
48+
and must be called after \fBslirp_open\fR and before \fBslirp_start\fR.
49+
50+
\fBslirp_set_addr\fR sets the IPv4 address and prefix of slirp in the virtual network.
51+
52+
\fBslirp_set_addr6\fR sets the IPv6 address and prefix of slirp in the virtual network.
53+
54+
\fBslirp_set_hostname\fR sets the hostname (for bootp).
55+
56+
\fBslirp_set_tftppath\fR sets the path of the directory shared if the ftfp service is enabled.
57+
58+
\fBslirp_set_bootfile\fR sets the bootfile (for bootp).
59+
60+
\fBslirp_set_dhcp\fR sets the lowest address assigned by the dhcp service.
61+
62+
\fBslirp_set_dnsaddr\fR sets the (virtual) IPv4 address for DNS forwarding.
63+
64+
\fBslirp_set_dnsaddr6\fR sets the (virtual) IPv6 address for DNS forwarding.
65+
66+
\fBslirp_set_vdnssearch\fR sets the dns search path (list of domains) advertised by dhcp.
67+
68+
.SH RETURN VALUE
69+
All these functions return 0 in case of success, -1 otherwise.
70+
71+
.SH SEE ALSO
72+
libslirp(3),
73+
.SH BUGS
74+
75+
Bug reports should be addressed to <info@virtualsquare.org>
76+
.SH AUTHOR
77+
Renzo Davoli <renzo@cs.unibo.it>: the idea of slirp is by Danny
78+
Gasparovski. This implementation of slirp has been forked from Qemu.
79+
Please refer to the LICENSE file in the source tree main directory for information about the license.

‎man/libslirpfwd.3

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
.\"* libslirp: slirp as a library
2+
.\" Copyright (C) 2014 Renzo Davoli. University of Bologna. <renzo@cs.unibo.it>
3+
.\"
4+
.\" This library is free software; you can redistribute it and/or
5+
.\" modify it under the terms of the GNU Lesser General Public
6+
.\" License as published by the Free Software Foundation; either
7+
.\" version 2.1 of the License, or (at your option) any later version.
8+
.\"
9+
.\" This library is distributed in the hope that it will be useful,
10+
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11+
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12+
.\" Lesser General Public License for more details.
13+
.\"
14+
.\" You should have received a copy of the GNU Lesser General Public
15+
.\" License along with this library; if not, write to the Free Software
16+
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17+
18+
.TH libslirpfwd 3 2016-11-16 "VirtualSquare" "Linux Programmer's Manual"
19+
.SH NAME
20+
slirp_add_fwd, slirp_remove_fwd, slirp_add_unixfwd, slirp_remove_unixfwd, slirp_add_cmdexec
21+
.SH SYNOPSIS
22+
.B #include <libslirp.h>
23+
.br
24+
.BI "int slirp_add_fwd(SLIRP * " slirp ", int " is_udp ","
25+
.BI "struct in_addr " host_addr ", int " host_port ","
26+
.BI "struct in_addr " guest_addr ", int " guest_port ");"
27+
.br
28+
.BI "int slirp_remove_fwd(SLIRP * " slirp ", int " is_udp ","
29+
.BI "struct in_addr " host_addr ", int " host_port ");"
30+
.br
31+
.BI "int slirp_add_unixfwd(SLIRP * " slirp ","
32+
.BI "struct in_addr " guest_addr ", int" guest_port ", char * " path ");"
33+
.br
34+
.BI "int slirp_remove_unixfwd(SLIRP * " slirp ","
35+
.BI "struct in_addr " guest_addr ", int " guest_port ");"
36+
.br
37+
.BI "int slirp_add_cmdexec(SLIRP * " slirp ", int " do_pty " , const void * " args ","
38+
.BI "struct in_addr " guest_addr ", int " guest_port ");"
39+
.sp
40+
These functions are provided by libslirp. Link with \fI-lslirp\fR.
41+
.SH DESCRIPTION
42+
Slirp, see liblirp(3), is a TCP/IP emulator. Slirp generates a virtual network using standard user privileges (no need for root access
43+
of CAP_NET_ADMIN).
44+
These functions manage port forwarding services.
45+
46+
\fBslirp_add_fwd\fR and \fBslirp_remove_fwd\fR respectively add and remove udp or tcp port forwarding services (depending upon the value of \fIis_udp\fR).
47+
\fIhost_addr\fR and \fIhost_port\fR are the IP address and port number bound for the service in the host system. All the connections or datagrams
48+
to \fIhost_addr\fR and \fIhost_port\fR will be diverted to \fIguest_addr\fR and \fIguest_port\fR in the slirp virtual network.
49+
50+
\fBslirp_add_unixfwd\fR and \fBslirp_remove_unixfwd\fR respectively add and remove forwarding service towards a PF_UNIX stream socket on the hosting system.
51+
All the connections from a node of the virtual network to \fIguest_addr\fR and \fIguest_port\fR will be diverted to the PF_UNIX
52+
bound to the pathname \fIpath\fR. This feature is commonly used to run X-window clients in the virtual network (e.g. the value of \fIpath\fR
53+
could be \fB/tmp/.X11-unix/X0\fR).
54+
55+
\fBslirp_unix_fwd\fR defines a diversion towards a command. A TCP connection to \fIguest_addr\fR and \fIguest_port\fR will cause the
56+
command whose argument array is \fIargs\fR to be started. A pty(7) pseudoterminal is created if \fIdo_pty\fR is true.
57+
58+
.SH RETURN VALUE
59+
All these functions return 0 in case of success, -1 otherwise.
60+
61+
.SH SEE ALSO
62+
libslirp(3),
63+
pty(3)
64+
.SH BUGS
65+
66+
Bug reports should be addressed to <info@virtualsquare.org>
67+
.SH AUTHOR
68+
Renzo Davoli <renzo@cs.unibo.it>: the idea of slirp is by Danny
69+
Gasparovski. This implementation of slirp has been forked from Qemu.
70+
Please refer to the LICENSE file in the source tree main directory for information about the license.

‎src/include/libslirp.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,13 @@ int slirp_close(SLIRP *slirp);
4646
int slirp_add_fwd(SLIRP *slirp, int is_udp,
4747
struct in_addr host_addr, int host_port,
4848
struct in_addr guest_addr, int guest_port);
49-
int slirp_remove_fwd(SLIRP *slirp, int is_udp,
49+
int slirp_del_fwd(SLIRP *slirp, int is_udp,
5050
struct in_addr host_addr, int host_port);
5151

5252
int slirp_add_unixfwd(SLIRP *slirp,
53-
struct in_addr host_addr, int host_port, char *path);
53+
struct in_addr guest_addr, int guest_port, char *path);
5454
int slirp_del_unixfwd(SLIRP *slirp,
55-
struct in_addr host_addr, int host_port);
55+
struct in_addr guest_addr, int guest_port);
5656

5757
int slirp_add_cmdexec(SLIRP *slirp, int do_pty, const void *args,
5858
struct in_addr guest_addr, int guest_port);

0 commit comments

Comments
 (0)