1gensio(5) File Formats Manual gensio(5)
2
6 gensio - How to specify a gensio
7
9 <type>[(options)][,gensio|terminaloptions]
10
12 gensio stands for GENeral Stream Input Output. It provides an abstrac‐
13 tion for all kinds of stream I/O, and even makes some packet I/O look
14 like stream I/O (like UDP). In particular, gensio makes it easy to
15 create encrypted and authenticated connections.
16 The gensio library specifies a connection (gensio) using a string for‐
18 mat. This consists of a gensio type, optional options in parenthesis.
19 For a terminal gensio (one that is at the bottom of the stack), it may
20 take more options separated by a comma. For filter gensios (ones not
21 on the bottom of the stack) another gensio must be specified after the
22 comma. For instance:
23 serialdev,/dev/ttyS0
25 specifies a serial port gensio. Or:
27 tcp(readbuf=100),localhost,4000
29 specifies a TCP connection with a 100 byte read buffer, to connect to
31 port 4000 on localhost. Or:
32 telnet,tcp,localhost,4000
34 specifies a telnet filter on top of a TCP connection.
36 When specifying a gensio, you can add quotes (single or double) to re‐
38 move the special meaning for some characters, so you can have commas in
39 options and such. They may also be escaped with a "\". For instance,
40 if you are specifying a laddr in an sctp address, you need to do this.
41 The following address:
42 sctp(laddr=localhost,4001),localhost,3023
44 will result in a failure because the option splitting code will split
46 at the commas. Instead, do:
47 sctp(laddr="localhost,4001"),localhost,3023
49 and it will work.
51 Accepter gensios, gensios used for accepting connections, as opposed to
53 connecting gensios, are specified in the same way. Each individual
54 type can vary, and some gensios are only connecting gensios. The op‐
55 tions can vary from the accepter and connecting gensios of the same
56 type. For instance, an accepting TCP gensio does not have to have a
57 hostname, but a connecting one does.
58 When an accepter gensio receives a connection, it will create an ac‐
60 cepted gensio. This works mostly like a connecting gensio, except some
61 functions may be limited. You may not be able to close and then open
62 an accepted gensio.
63 The gensio library has a concept of client and server. The accepted
65 gensios are generally considered servers. Connecting gensios are gen‐
66 erally considered clients. Some gensios may allow this to be overrid‐
67 den.
68 A gensio may be reliable or not. A reliable gensio will reliably de‐
70 liver all data in sequence, like TCP. An gensio that is not reliable
71 may drop data or deliver data out of sequence, like UDP. This can be
72 queried with gensio_is_reliable().
73 A gensio may be packet or not. A packet gensio will exactly match up
75 writes and reads. So if you write 15 bytes into one side, a 15 byte
76 read for that data will appear on the other side. A gensio that is not
77 packet will not respect write boundaries, that 15 byte write may result
78 in multiple reads or it may be combined with another write into more
79 than 15 bytes. Packet I/O requires careful use to make it work cor‐
80 rectly. If the gensio doesn't have room for another packet, a write
81 will succeed but write 0 bytes. Otherwise if you write larger than a
82 packet size, it will only take the number of bytes that can fit into a
83 packet, so it will truncate. This is useful if you want to stream over
84 a packet interface, but if you really want packets you have to make
85 sure all the sizes are set properly. Particularly, you must set the max
86 read and write size to the same value. You should check on writes that
87 it wrote all the data. You can do partial read handling, if you like,
88 but you will only get the rest of the packet on the second and follow‐
89 ing read.
90 A gensio may be message oriented. This implementation is stolen from
92 SCTP (even though it's not really supported on Linux at the moment).
93 It basically means you can explicitly mark message boundaries when
94 sending data, and that explicit mark will be set on the read side. You
95 do this by adding an "eom" auxdata on the write; the end of that write
96 it assumed to be the end of a message. If the write does not accept
97 all the data, the "eom" is ignored, you must write the remaining data
98 again with "eom" set. You may also do partial write of messages and
99 set "eom" at the end. On the receive side, "eom" will be set when the
100 end of a message is delivered. The data delivered in the receive call‐
101 back will be only the data for that message. If the user does not ac‐
102 cept all the data, the data left in the message is again presented to
103 the user with "eom" set.
104 The options vary greatly between the different gensios. Each gensio
106 type will be covered in a separate section. Also note that gensio
107 types can be dynamically added by the user, so there may be gensios
108 available that are not described here.
109 Unless otherwise noted, every gensio takes a:
111 readbuf=<n>
114 option to specify the read buffer size.
115
117 Every option to a gensio (including the serialdev and ipmisol options),
118 unless othersize stated, is available as a default for the gensios.
119 You can use gensio_set_default() to set the default value used by all
120 gensios allocated after that point. If you leave the class NULL, it
121 will set the base default, which will affect all gensios unless they
122 have an override. If you set the class, it will only affect gensios
123 with that class name.
124 Be very careful with some defaults. Setting "mode" default, for in‐
126 stance, could really screw things up.
127 For string defaults, setting the default value to NULL causes the gen‐
129 sio to use it's backup default.
130
132 Some gensio types support serial port setting options. Standard serial
133 ports, IPMI Serial Over LAN, and telnet with RFC2217 enabled.
134 A client serial gensio can set and get serial port options using the
136 sergensio_xxx() functions. Server serial gensios receive requests from
137 the client via GENSIO_EVENT_SER_xxx events in the callback.
138
140 Some gensios support the concept of a stream and/or a channel.
141 A stream is delivered as part of the normal data stream of a gensio.
143 The "default" stream will be treated normally. All other streams will
144 have "stream=<x>" given in the auxdata to specify which stream to write
145 on or which stream was read from. Streams cannot be individually flow
146 controlled.
147 A channel is a flow of data like a stream, but it can be individually
149 flow controlled. It appears as a new gensio in the GEN‐
150 SIO_EVENT_NEW_CHANNEL callback. You can create a channel with gen‐
151 sio_alloc_channel() and then open it with gensio_open(). Once open, a
152 channel works like a normal gensio. If you close the main channel for
153 a gensio, the other channels will stay open; the resources for the main
154 channel will still be kept around until all channels are closed.
155 See the indvidual gensio description for more information on streams
157 and channels.
158
160 The ssl and certauth gensios use public key cryptography. This section
161 gives a little overview of how that works. You can safely skip this
162 section if you already understand these concepts.
163 Public key cryptography is used to authenticate and encrypt information
165 at the beginning of a session. It is a fairly expensive operation and
166 is not generally used to encrypt information after the beginning.
167 In public key cryptography, you have three basic things: A private key,
169 a certificate (or public key), and a certificate authority (CA).
170 The private key is just that: private. You don't even send your pri‐
172 vate key to a certificate authority for signing of your certificate.
173 Keep it private, non-readable by everyone else. Protect it, if it be‐
174 comes known your certificate becomes useless to you, anyone can imper‐
175 sonate you.
176 The certificate is the public key, and is mathematically associated
178 with a single private key. It's just that, public, anyone can use it
179 to test that you have the private key by asking you to sign some data.
180 The data in the certificate (like the Common Name) is part of the cer‐
181 tificate. If that data is modified, the certificate validation will
182 fail.
183 The CA is generally a trusted third-party that validates you and signs
185 your certificate (generally for a fee). CAs issue their own public
186 certificates that are well-known and generally available on your sys‐
187 tem. The CA certificates are used to prove that your certificate is
188 valid.
189 SIGNING
191 The process if signing has been mentioned already, but not described.
192 Basically, you use your private key to generate a value over some given
193 data that proves you have the private key. The certificate is ised to
194 mathematically verify the signature.
195 Two things are normally done with this:
197 In a public key exchange, the entity wishing to be authorized sends a
199 certificate. The authorizing entity will look through it's CA for a
200 certificate that has signed the sent certificate. If the authorizing
201 entity finds a certificate that can be used to validate the sent cer‐
202 tificate, the sent certificate is valid.
203 After that, the authorizing entity sends some generally random data to
205 the other entity. The other entity will take that data, perhaps some
206 other important data that it want to make sure is not modified in the
207 transfer, and signs that data. It sends the signature back to the au‐
208 thorizing entity. The authorizing entity can then use the data and the
209 signature to validate that the sending entity has the private key asso‐
210 ciated with the certificate.
211 This is basically how https works. Note it is the web client that au‐
213 thenticates the web server, not the other way around. This proves that
214 you are connecting to the entity you say you are connecting to. The
215 authentication of a web client to the web server is generally done via
216 a different mechanism (though SSL/TLS used by the ssl gensio has a way
217 to do it, it is not generally used for that purpose).
218 In the web server scenario, data in the certificate (specifically the
220 Common Name and Subject Alternate Name) must match the name of the web
221 page to which you are connecting. The ssl and certauth gensios do not
222 do this authentication, that is up to the user if it is necessary.
223 ENCRYPTING
225 The certificate can be used to encrypt data that can only be decrypted
226 with the private key. When establishing an encrypted connection, this
227 is generally used to transfer a symmetric cryptography key from one en‐
228 tity to another (the authorizing entity to the requesting entity in the
229 case above). You could encrypt all the data with the public key, but
230 that is very expensive and in our example above would require certifi‐
231 cates and private keys on both ends.
232 SELF-SIGNED CERTIFICATES
234 It is possible to create a certificate that can act as its own certifi‐
235 cate authority. This is how ssh works. You create a public and pri‐
236 vate key. You put the public key in the .ssh/authorized_keys directory
237 on systems where you want to log in. The certificate acts as both the
238 public key (as part of the initial transfer) and the CA (in the autho‐
239 rized_key directory) for authorizing you use of the system you are log‐
240 ging in to.
241 ssh also stores places it has connected to in .ssh/known_hosts, which
243 is the CA in the opposite direction. This is why it asks you if you
244 have never connected to a system before, it doesn't have the key in its
245 CA. Or why, if you connect to a system you have connected to before
246 and the certificates don't match or fail validation, it complains about
247 it.
248 So if you are using self-signed certificates, you need to be careful to
250 put only ones you trust in the CA. This is obviously not possible in a
251 large system like the world wide web, thus the creation of third-party
252 trusted CAs.
253 TRUST AND CRYPTOGRAPHY
255 The above discussions mention trust several times. Cryptography does
256 not remove the need for trust. It just makes trust more convenient.
257 If someone sends you a certificate, you need to validate that it was
258 actually them that sent you the certificate, and that it was not modi‐
259 fied in transit. If you add that certificate to your CA, you are
260 trusting the certificate, and you better make sure (with fingerprints,
261 generally, see the openssl docs for details) that it came from a
262 trusted entity.
263 The hardest part of cryptography in general is key management. Break‐
265 ing cryptographic algorithms is really hard. Getting people to divulge
266 private keys or use the wrong keys is a lot easier.
267 For more on cryptography in general, and cryptography and trust, Bruce
269 Schneier has some excellent books on the subject.
270
272 Note that a single hostname may result in more than one address. For
273 instance, it may have both an IPv4 and IPv6 address. These are treated
274 just like multiple hostnames. For instance, if you use localhost as a
275 host name, you generally get the IPv4 and IPv6 version:
276 $ gensiot -a -p tcp,localhost,1234
278 Address 0(0): ipv6,::1,1234
279 Address 1(0): ipv4,127.0.0.1,1234
280 The hostname may be prefixed with ipv4 or ipv6, which will force the
282 connections to those protocols. Specifying ipv6n4 will create a socket
283 that is IPv6 but will handle IPv4 connections.
284 Note that using ipv6n4 will not automatically create a socket that is
286 available to IPv4. You can do, say tcp,ipv6n4,::1,1234 and it will
287 work, but since ::1 is not IPv4, you won't be able to get to it from
288 IPv4. You have to specify an IPv4 address, like:
289 tcp,ipv6n4,127.0.0.1,1234 which will result in a single IPv6 socket
290 mapped into IPv4 space:
291 $ gensiot -a -p tcp,ipv6n4,localhost,1234
293 Address 0(0): ipv6,::ffff:127.0.0.1,1234
294 If you do not specify a hostname on an accepting gensio (like
296 sctp,1234) it will only create an IPv6 socket that is IPv4 mapped.
297 This way it will accept both IPv4 and IPv6 connections. Even though
298 getaddrinfo would normally return two addresses, only the IPv6 one is
299 used unless there are no IPv6 addresses configured where it will return
300 an IPv4 address.
301 In general, for connecting gensios only the first address that is found
303 will be used. SCTP is the exception, it will do multi-homing on all
304 the addresses that come up. Do you may need to be fairly specific with
305 addresses.
306 In general IPv6 addresses are preferred if both are available.
308
310 Time consists of a set of numbers each followed by a single letter.
311 That letter may be 'D', 'H', 'M', 's', 'm', 'u', or 'n', meaning days,
312 hours, minutes, seconds, milliseconds, microseconds, or nanoseconds.
313 So, for instance, "10D5H4M9s100u" would be ten days, 5 hours, 4 min‐
314 utes, 9 seconds, 100 microseconds. If a plain number with no letter at
315 the end is given, the value may default to a specific unit. That will
316 be specified by the specific gensio.
317
319 tcp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
320 hostname = [ipv4|ipv6|ipv6n4,]<name>
321 A TCP connecting gensio must have the hostname specified. Multiple
323 hostname/port pairs may be specified. For a connecting TCP gensio,
324 each one will be tried in sequence until a connection is established.
325 For acceptor gensios, every specified hostname/port pair will be lis‐
326 tened to.
327 Dynamic Ports
329 For accepters, if the port is specified as zero, a random port in the
330 dynamic port range specified by IANA will be chosen. If more than one
331 address is present, the same port will be chosen for all addresses.
332 You can fetch the port using the gensio_acc_control() function with the
333 option GENSIO_ACC_CONTROL_LPORT.
334 Out Of Band Data
337 TCP supports out of band (oob) data, which is data that will be deliv‐
338 ered out of order as soon as possible. This comes in a normal read,
339 but with "oob" in the auxdata. You can send oob data by adding "oob"
340 to the write auxdata, but oob writes are limited to 1 byte and writing
341 any more than this results in undefined behavior. Note that "oobtcp"
342 is also delivered and accepted in auxdata, so you can tell TCP oob data
343 from other oob data.
344 Options
346 In addition to readbuf, the tcp gensio takes the following options:
347 nodelay[=true|false]
349 Sets nodelay on the socket.
350 laddr=<addr>
352 An address specification to bind to on the local socket to set
353 the local address.
354 reuseaddr[=true|false]
356 Set SO_REUSEADDR on the socket, good for accepting gensios only.
357 Defaults to true.
358 tcpd=on|print|off
360 Accepter only, sets tcpd handling on the socket. If "on", tcpd
361 is enforced and the connection is just closed on a tcpd denial.
362 "print" is like on, except it writes "Access Denied" on the
363 socket before closing it. "off" disabled tcpd handling on the
364 socket. Defaults to on. Not available if tcpd is disabled at
365 compile time.
366 tcpdname=<name>
368 Accepter only, sets the name to use for tcpd access control.
369 This defaults to "gensio", and the default can be overridden
370 with gensio_set_progname(). This option allows you to override
371 it on a per-gensio accepter basis. Not available if tcpd is
372 disabled at compile time.
373 Remote Address String
375 The remote address will be in the format "[ipv4|ipv6],<addr>,<port>"
376 where the address is in numeric format, IPv4, or IPv6.
377 Remote Address
379 TCP returns a standard struct sockaddr for GENSIO_CONTROL_RADDR_BIN
380 control.
381 Direct Allocation
383 Allocated as a terminal gensio with gdata as a "const struct gen‐
384 sio_addr *"
385
387 udp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
388 hostname = [ipv4|ipv6|ipv6n4,]<name>
389 A UDP gensio creates a UDP socket, but it makes it look like an unre‐
391 aliable stream of data. The specification is the same as a TCP socket,
392 except that a UDP socket is created, obviously.
393 The semantics of a UDP socket are a little bit strange. A connecting
395 UDP socket is fairly straightforward, it opens a local socket and sends
396 data to the remote socket.
397 An accepter gensio is not so straightforward. The accepter gensio will
399 create a new accepted gensio for any packet it receives from a new re‐
400 mote host. If you disable read on any of the accepted gensio or dis‐
401 able accepts on the accepting gensio, it will stop all reads on all
402 gensios associated with that accepting gensio.
403 Note that UDP accepter gensios are not really required for using UDP,
405 the are primarily there for handling ser2net accepter semantics. You
406 can create two connecting UDP gensios and communicate between them.
407 UDP gensios are not reliable, but are obviously packet-oriented.
409 Port 0 is supported just like TCP for accepters, see Dynamic Ports in
411 the TCP section above for details.
412 The destination address defaults to the one specified on the gensio
414 specifier (for connecting gensios) or the remote address that initiated
415 the connection (for accepting gensios), but may be overridden using
416 "addr:<addr>" in the write auxdata.
417 Options
419 In addition to readbuf, the udp gensio takes the following options:
420 laddr=<addr>
422 An address specification to bind to on the local socket to set
423 the local address.
424 nocon[=true|false]
426 Don't be connection oriented, just receive all packets and de‐
427 liver them without establishing connections. Only valid for the
428 client gensio. The receive address is passed into the auxdata
429 prefixed by "addr:", this is the address formatted by gen‐
430 sio_addr_to_str().
431 mloop[=true|false]
433 If false, multicast packets transmitted will not be received on
434 the local host. If true, they will.
435 mttl=[1-255]
437 Set the multicast time-to-live value. The default is 1, meaning
438 multicast stays in the local network. Increasing this value in‐
439 creases the number of hops over multicast routers a send packet
440 will traverse.
441 mcast=<addr>
443 Add an address to receive multicast packets on. There is no
444 port number, this is just addresses. You can specify multiple
445 addresses in a single multicast option and/or the multicast op‐
446 tion can be used multiple times to add multiple multicast ad‐
447 dresses.
448 reuseaddr[=true|false]
450 Set SO_REUSEADDR on the socket, good for connecting and accept‐
451 ing gensios. Defaults to false.
452 Remote Address String
454 The remote address will be in the format "[ipv4|ipv6],<addr>,<port>"
455 where the address is in numeric format, IPv4, or IPv6.
456 Remote Address
458 UDP returns a standard struct sockaddr for GENSIO_CONTROL_RADDR_BIN
459 control.
460 UDP Multicast
462 Multicast can be used on UDP gensios with the nocon, maddr and laddr
463 options. To set up a multicast, create a client UDP gensio and set the
464 laddr for the receive port and the destination address to the multicast
465 and enable nocon, like:
466 "udp(mcast='ff02::1',laddr='ipv6,3000',nocon),ff02::1,3000"
468 and you will receive and send data on the multicast address. The laddr
470 option is required to set the port to receive on. It means you will
471 have a local address, too, and will receive packets on that, too.
472 Direct Allocation
474 Allocated as a terminal gensio with gdata as a "const struct gen‐
475 sio_addr *"
476
478 sctp[(<options>)][,<hostname>],<port>[[,<hostname>],<port>[...]]
479 hostname = [ipv4|ipv6|ipv6n4,]<name>
480 An SCTP gensio is specified like a UDP or TCP one. However, the seman‐
482 tics are different. For a connecting gensio, it will attempt to create
483 a multi-homed connect with all the specified hostnames and ports. All
484 the ports must be the same.
485 For an accepter gensio, it will create a single socket with all the
487 specified addresses as possible destinations. Again, all the ports
488 must be the same.
489 SCTP gensios are reliable. They are not, at the moment, packet ori‐
491 ented. There is currently no support of SCTP_EXPLICIT_EOR in the Linux
492 implementation of SCTP, and without that it would be hard to make it
493 packet oriented.
494 When specifying IPv6 addresses that might map to IPv4, you must be
496 careful. If one side can do IPv4 and the other side can only do IPv6,
497 the connection may come up, but will disconnect quickly because it can‐
498 not communicate on the IPv4 side. For instance, the following ac‐
499 cepter:
500 tools/gensiot -a "sctp,ipv6,::,1234"
502 and the following connector:
504 tools/gensiot "sctp,::1,1234"
506 will fail this way because the connector will support IPv4 add but the
508 accepter will not.
509 Nagle and SCTP
511 SCTP implements the Nagle algorithm by default, which can interact
512 badly if sack_freq is set to more than one. At least Linux defaults
513 sack_freq to 2, but the gensio overrides this to avoid surprising be‐
514 haviour. What happens is in some situations you can get an outstanding
515 packet that is unacked, since sack_freq is greater than one. The Nagle
516 algorithm will not send any new data until any already sent data is
517 acked. So one end is waiting for a new packet to send a sack, and the
518 other end is holding data until it gets a sack. So you get stuck wait‐
519 ing for the sack_delay where the sack will go out and kick things back
520 off again.
521 You need to be aware of this if you modify sack_freq.
523 Options
525 In addition to readbuf, the sctp gensio takes the following options:
526 instreams=<n>
528 ostreams=<n>
530 These specify the number of incoming and outgoing streams for
531 the connection. The default is one. The stream is given in the
532 auxdata for read and write in the format "stream=<n>".
533 sack_freq=<n>
535 sack_delay=<n>
537 These specify the handling of selective acknowledgements
538 (sacks). sack_freq sets the number of outstanding packets that
539 must be received before sending a sack. The default is 1, mean‐
540 ing it doesn't wait at all. sack_delay sets the maximum time
541 before a sack is sent if outstanding packets are present, in
542 milliseconds. The default is 10, but this is disabled if
543 sack_freq is set to 1. Setting either of these to 0 enables the
544 system defaults.
545 nodelay[=true|false]
547 Sets nodelay on the socket.
548 laddr=<addr>
550 An address specification to bind to on the local socket to set
551 the local address.
552 reuseaddr[=true|false]
554 Set SO_REUSEADDR on the socket, good for accepting gensios only.
555 Defaults to true.
556 Port 0 is supported just like TCP for accepters, see Dynamic
558 Ports in the TCP section above for details.
559 SCTP support out of band (oob) data, which is data that will be
561 delivered out of order as soon as possible. This comes in a
562 normal read, but with "oob" in the auxdata. You can send oob
563 data by adding "oob" to the write auxdata.
564 See documentation on SCTP for more details.
566 Remote Address String
568 The remote address will be in the format
569 "[ipv4|ipv6],<addr>,<port>[;[ipv4|ipv6],<addr>,<port>[...]]" where the
570 address is in numeric format, IPv4, or IPv6. Each remote address for
571 the SCTP connection is listed.
572 Remote Address
574 SCTP returns a packed struct sockaddr for GENSIO_CONTROL_RADDR_BIN con‐
575 trol, per SCTP semantics.
576 Direct Allocation
578 Allocated as a terminal gensio with gdata as a "const struct gen‐
579 sio_addr *"
580
582 unix[(<options>)],<socket_path>
583 Create a unix domain socket as an accepter, or connect to a unix domain
585 socket as a connecter.
586 A file will be created with the given socket path, you must have per‐
588 missions to create a writeable file in that location. If the file al‐
589 ready exists, an error will be returned on an accepter socket unless
590 you specify delsock which will cause the file to be deleted.
591 You should read the unix(7) man page for details on the semantics of
593 these sockets, especially permissions. The options below allow setting
594 various permission and ownership of the file, but this may not have any
595 effect on who can open socket depending on the particular operating
596 system. Portable programs should not rely on these permissions for se‐
597 curity. Also note that Linux remote credentials are not currently im‐
598 plemented.
599 Options
601 In addition to readbuf, the unix gensio takes the following options:
602 delsock[=true|false]
604 If the socket path already exists, delete it before opening the
605 socket.
606 umode=[0-7|[rwx]*]
608 Set the user file mode for the unix socket file. This is the
609 usual read(4)/write(2)/execute(2) bitmask per chmod, but only
610 for the user portion. If a mode is specified, all other modes
611 default to "6" (rw) +unless they are specified, and the final
612 mode is modified by the umask +per standard *nix semantics. If
613 no mode is specified, it is set to +the default and not modi‐
614 fied. Note that the perm option below is +probably a better way
615 to set this.
616 gmode=[0-7|[rwx]*]
618 Set the group file mode for the unix socket file, see umode for
619 details.
620 omode=[0-7|[rwx]*]
622 Set the other file mode for the uix socket file, see umode for
623 details.
624 perm=[0-7][0-7][0-7]
626 Set the full mode for the unix socket file per standard *nix se‐
627 mantics, modified by umask as the above mode operations are.
628 owner=<name>
630 Set the owner of the unix socket file to the given user.
631 group=<name>
633 Set the group of the unix socket file to the given group.
634 Remote Address String
636 The remote address will be: "unix,<socket path>".
637 Remote Address
639 UNIX returns a standard struct sockaddr_un for GENSIO_CONTROL_RADDR_BIN
640 control.
641 Direct Allocation
643 Allocated as a terminal gensio with gdata as a "const struct gen‐
644 sio_addr *"
645
647 serialdev[(<options>)],<device>[,<serialoption>[,<serialoption>]]
648 A serialdev connection is a local serial port. The device is a
650 /dev/xxx type, and should be real stream device of some type that nor‐
651 mal termios or serial processing work on. For non-serial devices, use
652 the "dev" gensio.
653 This is, no surprise, a serial gensio.
655 You can also use "sdev" instead of "serialdev" for shorthand.
657 One problem with serialdev and UUCP locking is that if you fork() a
659 process while one is open, the forked process will have the serialdev
660 but the value in the UUCP lockfile will be incorrect. There's not much
661 that can be done about this, so be careful.
662 Options
664 In addition to readbuf, the serialdev gensio takes the following op‐
665 tions:
666 uucplock[=true|false]
668 Enable or disable UUCP locking on the device. The default is
669 true for everything except pty devices and /dev/tty. This is
670 ignored on systems that don't support this.
671 flock[=true|false]
673 Enable or disable flock locking on the device. The default is
674 true for everything except /dev/tty. Note that this does both
675 an "flock(fd, LOCK_EX | LOCK_NB)" and an "ioctl(fd, TIOCNXCL)"
676 to lock the device. This is ignored on systems that don't sup‐
677 port this.
678 drain_time=off|<time in 100ths of a second>
680 The total amount of time to wait for the data to be sent on the
681 serial port at close time. Close will be delayed this amount of
682 time, or until all the data is transmitted. Default is off.
683 When setting the default value for this, "off" will not be ac‐
684 cepted, use -1 instead.
685 char_drain_wait=off|<time in 100ths of a second>
687 At close time, if this much time elapses and no character is
688 sent, finish the close. Default is 50 (.5 seconds). Note that
689 if both this and drain_time are off, if the serial port is hung
690 on flow control, it will never close. When setting the default
691 value for this, "off" will not be accepted, use -1 instead.
692 wronly[=true|false]
694 Set the device to write only. Default is false.
695 rdonly[=true|false] Set the device to read only. Default is
696 false.
697 Serialoptions
699 There are a plethora of serialoptions, available as defaults:
700 [speed=]<speed><parity><databits><stopbits>
702 This is a normal serial port configuration specification, like
703 "9600N81". The "speed=" at the beginning is optional, but
704 "speed" is a default type for this.
705 wronly[=true|false]
707 This option is deprecated, use the "dev" gensio for non-serial
708 port devices and the wronly option in the parameters.
709 Set the device to write only. No termios definition is done on
711 the port. This can be done to talk to a line printer port, for
712 instance. False by default. Note that for historical reasons
713 this is different than the wronly option set in the parameters,
714 this one sets both turns off termio process and sets wronly.
715 nobreak[=true|false]
717 Clear the break line at start (or don't clear it). Default it
718 to not clear it (false).
719 rs485=off|<delay rts before send>:<delay rts after
721 send>[:<conf>[:<conf>]]
722 Set up RS-485 for the serial port. The first two parameters set
723 the RTS delay (in milliseconds) of RTS before and after sending.
724 The conf values can be: "rts_on_send" - RTS set when sending,
725 "rts_after_send" - RTS set after sending, "rx_during_tx" - can
726 receive and transmit at the same time, and "terminate_bus" - en‐
727 able bus termination.
728 Using "off" will disable rs485; that is useful for overriding a
730 user-defined default setting. Default is "off".
731 xonxoff[=true|false]
733 Enable/disable xon/xoff flow control. Default is false.
734 rtscts[=true|false]
736 Enable/disable rts/cts flow control. Default is false.
737 local[=true|false]
739 Ignore/don't ignore the modem control lines. The default it to
740 not ignore them (false). However, if you don't ignore the modem
741 control lines, it can result in long shutdown delays.
742 dtr[=on|off]
744 Force the DTR line to be on or off when the gensio is opened.
745 Note that the order of the dtr and rts options matter. Which‐
746 ever comes first in the options will be set first. This can be
747 useful if the lines need to be sequenced in a certain order for
748 the piece of hardware involved.
749 rts[=on|off]
751 Force the RTS line to be on or off when the gensio is opened.
752 See the dtr section above for notes on ordering of lines.
753 hangup-when-done[=true|false]
755 Lower/don't lower the modem control lines when the gensio is
756 closed. The default is not modify the value. On Unix, this
757 will modify HUPCL value set on the termios after close, because
758 there's no other real way to do that. On Windows, it will clear
759 DTR and RTS on close.
760 On the default for this, it's a integer, -1 means don't set the
762 value, 0 means turn off, 1 means turn on.
763 custspeed[=true|false]
765 Allow/don't allow setting of custom baud rates. Ignored if cus‐
766 tom baud rates are not supported. Normally only standard baud
767 rates are supported (1200, 2400, etc). If supported by the
768 hardware, this allows any arbitrary value to be set.
769 Remote Address String
771 The remote address string is the device and serial parms, in a format
772 like "9600N81[,<option>[,<option>[...]]]". Options are one of: XONX‐
773 OFF, RTSCTS, CLOCAL, HANGUP_WHEN_DONE, RTSHI, RTSLO, DTRHI, DRLO, off‐
774 line.
775 Remote ID
777 The remote ID for the serial dev is the file descriptor returned as an
778 integer.
779 Direct Allocation x
781 Allocated as a terminal gensio with gdata as a "const char *" with the
782 device and parameters string.
783
785 dev[(<options>)],<device> This is like a serialdev gensio, but doesn't
786 do any serial port processing like termios or break processing. This
787 can be used for /dev/lpX devices for instance. This is read/write by
788 default, you must set the wronly option to disable read access for a
789 write-only device and rdonly to disable write access for read-only de‐
790 vices.
791 This takes the same options as serialdev except that it does not do
793 locking. The drain_time and char_drain_wait options may or may not
794 work. It does not take serial options.
795
797 accepter = stdio[(options)]
798 connecting = stdio[(options)],<program>
799 The stdio gensio is a fairly strange one, but it's fairly useful.
801 A connecting stdio gensio runs the given program (unless self is set as
803 an option) and connects its standard input and output to the gensio's
804 main channel. So it's easy to run a program and interact with it. If
805 you want to get stderr from the gensio, open a channel on the main
806 channel gensio, see below.
807 NOTE: Though epoll() doesn't work with normal files, the stdio gensio
809 has special handling for normal files so they mostly work. This can
810 have surprising side effects if you use stdin as a normal file. When
811 you hit the end of stdin, the stdio gensio will return GE_REMCLOSE and
812 you may shut down the gensio and possibly lose any output going to std‐
813 out. Use the file gensio if you can.
814 For connecting gensios, in the forked process, the code will set the
816 effective (and saved) uid and guid to the current real uid and guid if
817 the effective and real uids are different. This way a user can set the
818 real uid and gid to what they want the program to run under, but keep
819 the effective uid and gid to the (probably root) values so they can be
820 restored to those values after opening the pty. The group list is also
821 set to the groups the real userid is in. Note that nothing is done if
822 the effective and real userids are the same.
823 If you have both stdin/stdout and stderr opened, you must close both of
825 them to completely close the gensio. You cannot re-open the gensio un‐
826 til both are closed.
827 The connecting gensio support the GENSIO_CONTROL_ENVIRONMENT control to
829 allow the environment to be set for the new process.
830 An accepting gensio immediately does a connection when started and con‐
832 nection stdin and stdout of the running program to the gensio.
833 Options
835 In addition to readbuf, a connecting stdio takes the following options:
836 self[=true|false]
838 Instead of starting a program, connect to the running program's
839 stdio. This is the same as an accepting stdio gensio, except
840 you don't have to go through the accept process.
841 console[=true|false]
843 Like self, except connect to the running program's console de‐
844 vice, /dev/tty on Unix and CONIN$/CONOUT$ on Windows. Useful
845 for reading passwords and such.
846 start-dir=path
848 Start the subprogram in the given path instead of the current
849 directory.
850 raw[=true|false]
852 For a "self", console, or accepter version of the gensio, put
853 the I/O in "raw" mode, meaning character at a time, turn off ^C,
854 etc. This will fail on pipes or files.
855 stderr-to-stdout
857 Send standard error output to standard out instead of having a
858 separate channel for it.
859 noredir-stderr
861 Do not modify the stderr for the program, use the calling pro‐
862 gram's stderr. This can be useful if you want to see stderr
863 output from a program.
864 Channels
866 The stdio connecting gensio that start another program does not provide
867 stderr as part of the main gensio. You must create a channel with gen‐
868 sio_alloc_channnel() and then open it get stderr output. The args for
869 gensio_alloc_channel() may be an optional "readbuf=<num>" and sets the
870 size of the input buffer.
871 Remote Address String
873 The remote address string is either "stdio,<args>" for the main channel
874 or "stderr,<args>" for the error channel. The args will be a set of
875 quoted strings with a space between each string, one for each argument,
876 with '"' around each argument, each '"' in the string converted to '\"'
877 and each '\' in the string converted to '\\'.
878 Remote ID
880 The remote ID is the pid for the remote device, only for connecting
881 gensios that start a program, not for any other type.
882 Direct Allocation
884 Allocated as a terminal gensio with gdata as a "const char * const
885 args[]" for the gensio. gdata is not used for the accepter.
886
888 connecting = echo[(options)]
889 The echo gensio just echos back all the data written to it. Useful for
891 testing.
892 Options
894 In addition to readbuf, a connecting echo takes the following options:
895 noecho[=true|false]
897 Instead of echoing the data, just become a data sink.
898 data=<str>
900 Supply the given data as the data to be read. When combined
901 with noecho, it will create a gensio that just supplies the
902 given data then returns a GE_REMCLOSE when done.
903 Remote Address String
905 The remote address string is "echo".
906 Direct Allocation
908 Allocated as a terminal gensio, gdata is not used.
909
911 connecting = file[(options)]
912 The file gensio opens an (optional) input file and (optional) output
914 file for the gensio. If you need to read/write a file in gensio, you
915 must use this. Semantics on files for stdio do not alway work cor‐
916 rectly.
917 If an input file is specified, data will be read from the input file
919 and delivered on the read interface of the gensio until end of file,
920 when the GE_REMCLOSE error will be returned.
921 If an output file is specified, data will be written to the output file
923 on writes. The output file is always ready to receive data.
924 Options
926 In addition to readbuf, a connecting file takes the following options:
927 infile=filename
929 Set the input filename.
930 outfile=filename
932 Set the output filename.
933 read_close[=true|false]
935 If this is true (the default), cause a GE_REMCLOSE error on read
936 when all the file data is ready. If false, just stop returning
937 data and don't do the GE_REMCLOSE. This is useful if you just
938 want to inject a bunch of data then do nothing.
939 create[=true|false]
941 Create the output file if it does not exist. Ignored for read.
942 append[=true|false]
944 Open the file in append mode. If not specified, it will be
945 opened at the beginning of the file and if writing, it will
946 overwrite. Ignored for read.
947 trunc[=true|false]
949 Truncate the file on open. All data will be deleted from the
950 file when opened. Ignored for read.
951 binary[=true|false]
953 Open the file in binary mode. This is ignored on *nix systems,
954 but for Windows it affects how newlines are handled.
955 umode=[0-7|[rwx]*]
957 Set the user file mode for the file if the file is created.
958 This is the usual read(4)/write(2)/execute(2) bitmask per chmod,
959 but only for the user portion. If a mode is specified, all
960 other modes default to "6" (rw) +unless they are specified, and
961 the final mode is modified by the umask +per standard *nix se‐
962 mantics. If no mode is specified, it is set to +the default and
963 not modified. Note that the perm option below is +probably a
964 better way to set this.
965 gmode=[0-7|[rwx]*]
967 Set the group file mode for the file if the file is created, see
968 umode for details.
969 omode=[0-7|[rwx]*]
971 Set the other file mode for the file if the file is created, see
972 umode for details.
973 perm=[0-7][0-7][0-7]
975 Set the full mode for the file per standard *nix semantics, mod‐
976 ified by umask as the above mode operations are.
977 Remote Address String
979 The remote address string is "file([infile=<filename][,][outfile=<file‐
980 name>])".
981 Direct Allocation
983 Allocated as a terminal gensio, gdata is not used.
984
986 accepter = dummy
987 The dummy gensio accepter is useful for place holding, where you don't
989 want a real working accepter but need to put something.
990 As you might guess, it doesn't do anything.
992 Direct Allocation
994 Allocated as a terminal gensio, gdata is not used.
995
997 ipmisol[(options)],<openipmi arguments>[,ipmisol option[,...]]
998 An ipmisol gensio creates an IPMI Serial Over LAN connection to an IPMI
1000 server. See the OpenIPMI documentation for information on the argu‐
1001 ments.
1002 This is a serial gensio, but the baud rate settings are fairly limited.
1004 Options
1006 In addition to readbuf, the ipmisol gensio takes the following options:
1007 writebuf=<n>
1009 to set the size of the write buffer.
1010 It also takes the following ipmisol options:
1012 9600, 19200, 38400, 57600, 115200
1014 Baud rate, 9600 by default. Anything after the number is ig‐
1015 nored, for compatibility with things like "N81". You cannot set
1016 those values for ipmisol, they are fixed at "N81".
1017 nobreak[=true|false]
1019 Disable break processing. False by default.
1020 authenticated[=true|false]
1022 Enable or disable authentication. True by default.
1023 encrypted[=true|false]
1025 Enable or disable encrypted. True by default.
1026 deassert-CTS-DCD-DSR-on-connect[=true|false]
1028 False by default
1029 shared-serial-alert=fail|deferred|succeed
1031 Behavior of handling serial alerts. fail by default.
1032 ack-timeout=<number>
1034 The time (in microseconds) when an ack times out. 1000000 by
1035 default.
1036 ack-retries=<number>
1038 The number of times (ack-timeouts) an ack is re-sent before giv‐
1039 ing up. 10 by default.
1040 Direct Allocation
1042 Allocated as a terminal gensio with gdata as a "const char *".
1043
1045 accepter = telnet[(options)]
1046 connecting = telnet[(options)]
1047 A telnet gensio is a filter that sits on top of another gensio. It
1049 runs the standard telnet protocol andn support RFC2217.
1050 Options
1052 In addition to readbuf, the telnet gensio takes the following options:
1053 writebuf=<n>
1055 set the size of the write buffer.
1056 rfc2217[=true|false]
1058 enable or disable RFC2217 mode for this gensio. If this is en‐
1059 abled and the remote end of the connection supports RFC2217
1060 also, the gensio will be set up as a serial gensio and you can
1061 do normal serial gensio handling on it.
1062 winsize[=true|false]
1064 enable or disable RFC1073, window size change notification. De‐
1065 fault is false.
1066 mode=client|server
1068 Set the telnet mode to client or server. This lets you run a
1069 telnet server on a connecting gensio, or a telnet client on an
1070 accepter gensio.
1071 Remote info
1073 telnet passes remote id, remote address, and remote string to the child
1074 gensio.
1075
1077 accepter = ssl[(options)]
1078 connecting = ssl[(options)]
1079 An SSL gensio runs the SSL/TLS protocol on top of another gensio. That
1081 gensio must be reliable.
1082 Use is pretty straightforward. The hardest part about using the SSL
1084 gensio is the certificates. A server SSL gensio must be given a cer‐
1085 tificate and a key. A client SSL gensio must be given a certificate
1086 authority. A client will user the certificate authority to verify that
1087 the server has the proper certificate and keys.
1088 The gensio has options to have the server request the certificate from
1090 the client and validate it.
1091 SSL gensios are reliable. They are also packet-oriented.
1093 Options
1095 In addition to readbuf, the SSL gensio takes the following options:
1096 writebuf=<n>
1098 set the size of the write buffer.
1099 CA=<filepath>
1101 Set a place to look for certificates for authorization. If this
1102 ends in a "/", then this is expected to be a directory that con‐
1103 tains files with certificates that must be hashed per OpenSSL
1104 (see the "openssl rehash" command for details. Otherwise it is
1105 a single file that contains one or more certificates. The de‐
1106 fault CA path is used if not specified. Note that setting this
1107 to an empty string disables it, so you can override a default
1108 value if necessary.
1109 key=<filename>
1111 Specify the file to get the private key for the server. This is
1112 required for servers. It may be specified for clients, and is
1113 required for the client if the server requires a certificate (it
1114 has CA set).
1115 cert=<filename>
1117 Specify the file that contains the certificate used for the con‐
1118 nection. If this is not specified, the certificate is expected
1119 to be in the key file. Note that setting this to an empty
1120 string disables it, so you can override a default value if nec‐
1121 essary.
1122 mode=client|server
1124 Normally an accepter gensio is in server mode and a connecting
1125 gensio is in client mode. This can be used to switch the roles
1126 and run in SSL server mode on a connecting gensio, or vice
1127 versa.
1128 con-timeout=<gtime>
1130 Set the timeout for a connection to complete. If the connect
1131 process does not complete in this amount of time, the connection
1132 will be dropped. The default is 60 seconds. See the "gtime"
1133 section for more info on how to set the time. Note that the de‐
1134 fault setting for con-timeout is not a gtime, it is an integer
1135 in seconds.
1136 clientauth[=true|false]
1138 Normally a client is not authorized by the server. This re‐
1139 quires that the client provide a certificate and authorizes that
1140 certificate. Ignored for client mode.
1141 allow-authfail[=true|false]
1143 Normally if the remote end certificate is not valid, the SSL
1144 gensio will close the connection. This open allows the open to
1145 succeed with an invalid or missing certificate. Note that the
1146 user should verify that authentication is set using gen‐
1147 sio_is_authenticated().
1148 Verification of the common name is not done. The application
1150 should do this, it can fetch the common name and other certifi‐
1151 cate data through a control interface.
1152 You can use self-signed certificates in this interface. Just be
1154 aware of the security ramifications. This gensio is fairly
1155 flexible, but you must use it carefully to have a secure inter‐
1156 face.
1157 The SSL gensio will call the gensio event callback (client) or
1159 the gensio acceptor event callback (server) after the certifi‐
1160 cate is received but before it is validated with the GEN‐
1161 SIO_EVENT_PRECERT_VERIFY or GENSIO_ACC_EVENT_PRECERT_VERIFY
1162 events. This allows the user to validate data from the certifi‐
1163 cate (like common name) with GENSIO_CONTROL_GET_PEER_CERT_NAME
1164 or set a certificate authority for the validation with GEN‐
1165 SIO_CONTROL_CERT_AUTH.
1166 Remote info
1168 ssl passes remote id, remote address, and remote string to the child
1169 gensio.
1170
1172 accepter = certauth[(options)]
1173 connecting = certauth[(options)]
1174 A certauth gensio runs an authentication protocol to on top of another
1176 gensio. That gensio must be reliable and encrypted.
1177 This is like the reverse of SSL. The client has a key and certificate,
1179 the server has a certificate authority (CA). This also supports pass‐
1180 word authentication.
1181 Once authentication occurs, this gensio acts as a passthrough. The
1183 readbuf option is not available in the gensio.
1184 Options
1186 The certauth gensio takes the following options:
1187 CA=<filepath>
1189 Set a place to look for certificates for authorization. If this
1190 ends in a "/", then this is expected to be a directory that con‐
1191 tains files with certificates that must be hashed per OpenSSL,
1192 see the gensio-keygen(1) in the rehash section for details.
1193 Otherwise it is a single file that contains one or more certifi‐
1194 cates. The default CA path for openssl is used if not speci‐
1195 fied. This is used on the server only, it is ignored on
1196 clients. Note that setting this to an empty string disables it,
1197 so you can override a default value if necessary.
1198 key=<filename>
1200 Specify the file to get the private key for the client. This is
1201 required for clients. It is ignored on server.
1202 cert=<filename>
1204 Specify the file to get the private key for the client. This is
1205 required for clients. It is ignored on server. If this is not
1206 specified, the certificate is expected to be in the key file.
1207 Note that setting this to an empty string disables it, so you
1208 can override a default value if necessary.
1209 username=<name>
1211 Specify a username to authenticate with on the remote end. This
1212 is required for the client. It is ignored on the server.
1213 service=<string>
1215 Set the remote service requested by the client. Optional, but
1216 the other end may reject the connection if it is not supplied.
1217 Ignored on the server.
1218 password=<string>
1220 Specify the password to use for password authentication. This
1221 is not recommended, the callback is more secure to use.
1222 mode=client|server
1224 Normally an accepter gensio is in server mode and a connecting
1225 gensio is in client mode. This can be used to switch the roles
1226 and run in server mode on a connecting gensio, or vice versa.
1227 allow-authfail[=true|false]
1229 Normally if the remote end certificate is not valid, the cer‐
1230 tauth gensio will close the connection. This open allows the
1231 open to succeed with an invalid or missing certificate. Note
1232 that the user should verify that authentication is set using
1233 gensio_is_authenticated().
1234 use-child-auth[=true|false]
1236 If the child gensio is authenticated, then do not run the proto‐
1237 col, just go straight into passthrough mode and don't do any au‐
1238 thentication.
1239 enable-password[=true|false]
1241 On the server, allow passwords for login. On the client, send a
1242 password if asked for one. By default passwords are disabled.
1243 Use of passwords is much less secure than certificates, so this
1244 is discouraged.
1245 enable-2fa[=true|false]
1247 On the server, request 2-factor authentication data from the
1248 client. This is only useful for situations where the 2-factor
1249 data is known before startup, like Google Authenticator or other
1250 things of that nature. It is not useful for text/email types of
1251 things that send the data after the connection is initiated.
1252 But those are usually interactive and can be handled with inter‐
1253 active methods.
1254 2fa=<string>
1256 On the client, provide the given 2-factor authentication data to
1257 the server if it asks for it.
1258 Verification of the common name is not done. The application should do
1260 this, it can fetch the common name and other certificate data through a
1261 control interface. It may also use the username fetched through the
1262 control interface.
1263 con-timeout=<gtime>
1265 Set the timeout for a connection to complete. If the connect
1266 process does not complete in this amount of time, the connection
1267 will be dropped. The default is 60 seconds. See the "gtime"
1268 section for more info on how to set the time. Note that the de‐
1269 fault setting for con-timeout is not a gtime, it is an integer
1270 in seconds.
1271 You can use self-signed certificates in this interface. Just be
1273 aware of the security ramifications. This gensio is fairly
1274 flexible, but you must use it carefully to have secure authenti‐
1275 cation.
1276 The certauth gensio has 4 major callbacks dealing with authenti‐
1278 cation of the user. They may or may not be called depending on
1279 the circumstances. The normal events come in if you have allo‐
1280 cated a gensio and are doing an open. The _ACC_ events come in
1281 if it is coming in from an accept and there is no gensio re‐
1282 ported yet. In the _ACC_ case, be careful, do not use the given
1283 gensio for anything but checking certificate and username param‐
1284 eters, and do not save it.
1285 All these calls should return 0 if they want the authentication
1287 to immediately succeed, EKEYREJECTED if they reject the authen‐
1288 tication, ENOTSUP if they want certauth to ignore that part of
1289 the authentication, or any other errno will result in the con‐
1290 netion being shut down.
1291 The callbacks are:
1293 GENSIO_EVENT_AUTH_BEGIN / GENSIO_ACC_EVENT_AUTH_BEGIN
1295 On the server side, this is called when to authentication is re‐
1296 quested buy the client. The username will be available if the
1297 user provided it via GENSIO_CONTROL_USERNAME.
1298 GENSIO_EVENT_PRECERT_VERIFY / GENSIO_ACC_EVENT_PRECERT_VERIFY
1300 On the server side, thi is called after the certificate has been
1301 received but before it is verified. The user can use this to
1302 query the certificate and update the certificate authority based
1303 on username or certificate information.
1304 GENSIO_EVENT_VERIFY_PASSWORD / GENSIO_ACC_EVENT_VERIFY_PASSWORD
1306 On the server side, this is called if the certificate verifica‐
1307 tion has failed and after the password has been requested from
1308 the remote end. The password is passed in, it is cleared imme‐
1309 diately after this call.
1310 GENSIO_EVENT_REQUEST_PASSWORD / GENSIO_ACC_EVENT_REQUEST_PASSWORD
1312 On the client side, this is called if the server requests that a
1313 password be sent and the password is not already set for the
1314 gensio. The requested password is immediately cleared after be‐
1315 ing sent to the server.
1316 Remote info
1318 certauth passes remote id, remote address, and remote string to the
1319 child gensio.
1320
1322 accepter = mux[(options)]
1323 connecting = mux[(options)]
1324 A mux gensio is a gensio filter that allows one or more channels to be
1326 created on top of a single gensio, multiplexing the connection. Each
1327 channel has full individual flow-control. The channels are message
1328 oriented as described above, and use can use a mux without additional
1329 channels to just do message demarcation. They also support out-of-
1330 bounds messages.
1331 Options
1333 A mux gensio takes the following options:
1334 max_channels=<n>
1336 Allow at most <n> channels to be created in the mux. The de‐
1337 fault is 1000. The minimum value of <n> is 1, the maximum is
1338 65536.
1339 service=<string>
1341 Set the remote service requested by the client. Optional, but
1342 the other end may reject the connection if it is not supplied.
1343 Ignored on the server.
1344 mode=client|server
1346 By default a mux accepter is a server and a mux connecter is a
1347 client. The protocol is mostly symmetric, but it's hard to kick
1348 things off properly if both sides try to start things. This op‐
1349 tion lets you override the default mode in case you have some
1350 special need to do so.
1351 When the open is complete on the mux gensio, it will work just like a
1353 transparent filter with message demarcation. In effect, you have one
1354 channel open.
1355 Creating Channels
1357 To create a channel, call the gensio_alloc_channel() function on the
1358 mux gensio. This will return a new gensio that is a channel on the mux
1359 gensio. You can pass in arguments, which is an array of strings, cur‐
1360 rently readbuf, writebuf, and service are accepted. The service you
1361 set here will be set on the remote channel so the other end can fetch
1362 it. The new channel needs to be opened with gensio_open() before it
1363 can be used.
1364 As you might imaging, the other end of a mux needs to know about the
1366 new channel. If one end (either end, doesn't matter) calls gensio_al‐
1367 loc_channel() and then opens the new channel, the other end will get a
1368 GENSIO_EVENT_NEW_CHANNEL event as described in the Streams and Channels
1369 section. You can call it using any mux channel. The first element in
1370 the auxdata is the service.
1371 You can modify the service value after you allocate the channel but be‐
1373 fore you open it.
1374 Out Of Band Messages
1376 mux support out of band (oob) data, which is data that will be deliv‐
1377 ered normally. This comes in a normal read, but with "oob" in the aux‐
1378 data. You can send oob data by adding "oob" to the write auxdata. You
1379 should normally use the "eom" flag so the end of the out of band mes‐
1380 sages ismarked.
1381 This is so you can send special data outside of the normal processing
1383 of data.
1384 Mux Events
1386 As you might imaging, normal data events come through the gensio chan‐
1387 nel they are associated with. Close events will, too. If a mux gensio
1388 closes abnormally (like the underlying connection fails) you will get a
1389 read error on each channel.
1390 New channel events (and other global events coming from lower gensios,
1392 like if you are running over ssl or telnet) come in through the origi‐
1393 nal gensio normally. However, you can close that, another channel will
1394 be chosen to receive those event. In general, it's best to handle the
1395 global events on all channels and not assume.
1396 Closing and Freeing a Mux
1398 To close a mux gensio, just close all channels associated with it.
1399 There is no global close mechanism (you would not believe the complex‐
1400 ity that adds). Once you have closed a mux gensio, you can re-open it
1401 with gensio_open(). It will not recreate all the channels for you, you
1402 will have one channel, and the channel you use to call gensio_open()
1403 will become the first channel.
1404 You cannot re-open individual channels.
1406 To free a mux gensio, you must free all the channels on it.
1408
1410 connecting = pty[(options)][,<program>]
1411 Create a pty and optionally run a program on the other end of it. With
1413 a program specified, this is sort of like stdio, but the program is
1414 running on a terminal. Only connection gensios are supported.
1415 pty has some unusual handling to allow execution of login shells of
1417 users from root.
1418 In Unix type systems, if the first character of the program is '-', it
1420 is removed from the execution of the command but left in argv[0]. This
1421 will cause a shell to act as a login shell.
1422 On Unix type systems, in the forked process, the code will set the ef‐
1424 fective (and saved) uid and guid to the current real uid and guid if
1425 the effective and real uids are different. This way a user can set the
1426 real uid and gid to what they want the program to run under, but keep
1427 the effective uid and gid to the (probably root) values so they can be
1428 restored to those values after opening the pty. The group list is also
1429 set to the groups the real userid is in. Note that nothing is done if
1430 the effective and real userids are the same.
1431 On Windows, the new process is set to the user in the impersonation to‐
1433 ken if it is set. In that case, the new process will be run in a new
1434 process group. If no impersonation token is set, the new process will
1435 run as the user of calling process in the same process group as the
1436 calling process.
1437 The pty gensio supports the GENSIO_CONTROL_ENVIRONMENT control to allow
1439 the environment to be set for the new process. GENSIO_CONTROL_ARGS
1440 sets the arguments as an argv array. GENSIO_CONTROL_WIN_SIZE sets the
1441 terminal size in characters. GENSIO_CONTROL_START_DIR sets the direc‐
1442 tory the new process runs in.
1443 If no program is specified, when the pty gensio is opened it will just
1445 create the pty but won't attach anything to it. Another program can
1446 open the pty. You can get the slave pty device by getting the local
1447 address string.
1448 Options
1450 In addition to readbuf, the pty gensio takes the following options.
1451 These options are only allowed if the pty is unattached. ptys with
1452 programs run on them need to follow the standard semantics.
1453 link=<filename>
1455 create a symbolic link from filename to the pty name. This way
1456 you can have a fixed reference to refer to the pty. Standard
1457 permissions apply. Without forcelink the open will file if
1458 filename already exists. Unix only.
1459 forcelink[=true|false]
1461 if link is specified, if a file already exists where the sym‐
1462 bolic link is, replace it. Be careful, it deletes whatever is
1463 there indiscriminately.
1464 start-dir=path
1466 Start the subprogram in the given path instead of the current
1467 directory.
1468 raw[=true|false]
1470 causes the pty to be set in raw mode at startup. This is impor‐
1471 tant for anything that will start writing immediately to the
1472 pty. If you don't set this, echo will be on and writes on the
1473 master will be echoed back. In general, this is useful for un‐
1474 attached ptys. It was added for testing, but will be usedful in
1475 many situations.
1476 umode=[0-7|[rwx]*]
1478 Set the user file mode for the pty slave. This is the usual
1479 read(4)/write(2)/execute(2) bitmask per chmod, but only for the
1480 user portion. If a mode is specified, all other modes default
1481 to "6" (rw) +unless they are specified, and the final mode is
1482 modified by the umask +per standard *nix semantics. If no mode
1483 is specified, it is set to +the default and not modified. Note
1484 that the perm option below is +probably a better way to set
1485 this.
1486 gmode=[0-7|[rwx]*]
1488 Set the group file mode for the pty slave, see umode for de‐
1489 tails.
1490 omode=[0-7|[rwx]*]
1492 Set the other file mode for the pty slave, see umode for de‐
1493 tails.
1494 perm=[0-7][0-7][0-7]
1496 Set the full mode for the pty per standard *nix semantics, modi‐
1497 fied by umask as the above mode operations are.
1498 owner=<name>
1500 Set the owner of the slave pty to the given user.
1501 group=<name>
1503 Set the group of the slave pty to the given group.
1504 user=<name>
1506 Windows only, create the process under the given user instead of
1507 the calling process' user. This generally required special
1508 privileges.
1509 passwd=<name>
1511 Windows only, user must be specified to use. Log on the user
1512 with the given password. If a password is not given, an S4U lo‐
1513 gon will be attempted, but that may not work so well as some
1514 things are missing from the access token of the user.
1515 NOTE: There are significant security issues with passing a pass‐
1517 word this way. You must use proper password handling. mod‐
1518 ule=<name> Windows only, user must be specified to use. Create
1519 the new user token with the given module. If not specified,
1520 "gensio" is used.
1521 Remote Address String
1523 The remote address string the program and arguments run on the pty.
1524 The argiuments will be a set of quoted strings with a space between
1525 each string, one for each argument, with '"' around each argument, each
1526 '"' in the string converted to '\"' and each '\' in the string con‐
1527 verted to '\\'.
1528 Remote Address
1530 The address is a pointer to an integer, the ptym file descriptor is re‐
1531 turned. addrlen must be set to sizeof(int) when passed in.
1532 Local Address String
1534 This returns the device of the pty, generally /dev/pts/<n>. This is
1535 useful for pty gensios with no program, it allows you to get the value
1536 for the other end to connect to. Note that if you close and re-open a
1537 pty gensio, you may be a different local address string.
1538 Direct Allocation
1540 Allocated as a terminal gensio with gdata as a "const char * const
1541 args[]".
1542
1544 accepter = msgdelim[(options)]
1545 connecting = msgdelim[(options)]
1546 A message delimiter converts an unreliable stream (like a serial port)
1548 into an unreliable packet interface. This is primarily to allow a re‐
1549 liable packet interface like relpkt to run on top of a serial port. It
1550 does not support streaming of data, so it's not very useful by itself.
1551 Messages are delimited with a start of message and end of message and
1553 have a CRC16 on the end of them.
1554 This is primarily for use on serial ports and other streams that can
1556 munge up the data. Use the mux gensio for TCP and such.
1557 The default buffer size is 128 bytes, which is ok for a reasonably fast
1559 serial port interface.
1560 Options
1562 In addition to readbuf, the msgdelim gensio takes the following op‐
1563 tions:
1564 writebuf=<n>
1566 set the size of the write buffer.
1567 crc[=on|off]
1569 Enable/disable the CRC at the end of the packet. Useful if you
1570 are running over a reliable protocol, and especially for testing
1571 relpkt so you can fuzz it and bypass the crc errors.
1572
1574 accepter = relpkt[(options)]
1575 connecting = relpkt[(options)]
1576 Converts an unreliable packet interface (currently only UDP and msgde‐
1578 lim) into a reliable packet interface. This lets you have a reliable
1579 connection over a serial port (with msgdelim) or UDP.
1580 Note that UDP is not recommended, it doesn't handle flow control and
1582 such in a friendly manner.
1583 relpkt is unusual in dealing with clients and servers. The protocol is
1585 symmetric, for the most part, you can start two clients and they will
1586 connect to each other, if they are started relatively close in time to
1587 avoid one timing out. A relpkt server will simply wait forever for an
1588 incoming connection on an open.
1589 relpkt does not support readbuf. It supports the following:
1591 max_pktsize=<n>
1593 Sets the maximum size of a packet. This may be reduced by the
1594 remote end, but will never be exceeded. This must be at least 5
1595 bytes shorter than the maximum packet size of the interface be‐
1596 low it. This defaults to 123 (msgdelim max packet size - 5).
1597 If run over UDP, this should probably be increased for perfor‐
1598 mance.
1599 max_packets=<n>
1601 Sets the maximum number of outstanding packets. This may be re‐
1602 duced by the remote end, but will never be exceeded.
1603 mode=client|server
1605 By default a relpkt is a server on an accepter and a client on a
1606 connecter. See the discussion above on clients and servers.
1607 timeout=<gtime>
1609 Specify the time for a timeout. If relpkt sends a message re‐
1610 quiring an ack, it will wait this long before resending the
1611 packet. See the "gtime" section for more info on how to set the
1612 time. If you don't specify a time modifier, the default is in
1613 seconds. The default is one second.
1614 max_timeouts=<n>
1616 The maximum number of timeouts before giving up on a connection.
1617 The default is 5.
1618
1620 accepter = ratelimit[(options)]
1621 connecting = ratelimit[(options)]
1622 Limit the transmit rate of data going through this filter gensio. A
1624 number of bytes is let through, then transmit is delayed until the
1625 given delay has passed. Receive is not currently rate limited, but
1626 that may be added in the future.
1627 xmit_len=<n>
1629 The number of bytes to allow before a delay. Note that the de‐
1630 lay occurs after a single write succeeds, so if a single byte is
1631 written it will delay. If a write is done of more than this
1632 length, it will be limited to this length. Defaults to one.
1633 xmit_delay=<gtime>
1635 The amount of time to wait between writes. See the "gtime" sec‐
1636 tion for information for this time specification. This must be
1637 supplied.
1638
1640 accepter = trace[(options)]
1641 connecting = trace[(options)]
1642 A transparent gensio that allows the data passing through it to be sent
1644 to a file. Useful for debugging. It can also block data in either di‐
1645 rection.
1646 Note that the trace gensio only prints data that is accepted by the
1648 other end. So, for instance, if the trace gensio receives 100 bytes of
1649 read data, it will deliver it immediately to the gensio above it. If
1650 that only accepts 40 bytes, trace will only print 40 bytes and will
1651 only accept 40 bytes from the gensio below it. Same for sent data.
1652 Options
1654 trace does not support readbuf. It supports the following options:
1655 dir=none|read|write|both
1657 Sets what data is traced. "none" means no data is traced (the
1658 default), "read" traces data flowing up the gensio stack (read
1659 by the parent), write traces data flowing down the gensio stack
1660 (written by the parent), and "both" traces reads and writes.
1661 block=none|read|write|both
1663 Blocks data in one or both directions. "none" means data flows
1664 both directions (the default), "read" means data flowing up the
1665 gensio stack is discarded, write means data flowing down the
1666 gensio stack is discarded, and "both" discards both reads and
1667 writes. Data that is discarded is not traced.
1668 raw[=yes|no]
1670 If set, traced data will be written as raw bytes. If not set,
1671 traced data will be written in human-readable form.
1672 file=<filename>
1674 The filename to write trace data to. If not supplied, tracing
1675 is disabled. Note that unless delold is specified, the file is
1676 opened append, so it will add new trace data onto the end of an
1677 existing file.
1678 stderr[=yes|no]
1680 Send the trace output to standard error. Overrides file.
1681 stdout[=yes|no]
1683 Send the trace output to standard output. Overrides file and
1684 stderr.
1685 delold[=yes|no]
1687 Delete the old data in the file instead of appending to the
1688 file.
1689
1691 accepter = perf[(options)]
1692 connecting = perf[(options)]
1693 A gensio for measuring throughput for a connection. This allows the
1695 performance of a connection to be measured. It does not pass any data
1696 through. Instead, it writes raw data to the lower layer (if write_len
1697 is set) and reads data from the lower layer, counting the bytes and
1698 measuring the time.
1699 To the upper layer, perf prints out statistics about the data transfer.
1701 It prints out the number of bytes written and read each second, and at
1702 the end it prints a total.
1703 If write_len and/or expect_len is non-zero, then the filter will return
1705 GE_REMCLOSE when it runs out of write data and has received all ex‐
1706 pected data. If both are zero, the connection will not be closed by
1707 the gensio.
1708 Options
1710 perf does not support readbuf. It supports the following options:
1711 writebuf=<n>
1713 Sets the size of the buffer to write to the child gensio. Each
1714 write will be this size. This defaults to zero.
1715 write_len=<n>
1717 The number of bytes to write.
1718 expect_len=<n>
1720 The number of bytes to expect from the other end.
1721
1723 accepter = conacc[(options)],<gensio string>
1724 conacc is a gensio accepter that takes a gensio as a child. When the
1726 accepter is started, it opens the child gensio. When the child gensio
1727 finishes the open, it reports a new child for the accepter. The re‐
1728 ported gensio can be used normally.
1729 When the gensio is closed, when the close completes the accepter will
1731 attempt to re-open the gensio immediately and will disable itself if
1732 the connect fails, unless retry-time is set. This means that if the
1733 gensio has some sort of random address (like a pty or a tcp address
1734 with the port set to zero) you can get a different address for the re-
1735 opened gensio. So you must refetch the local address or local port in
1736 this case.
1737 Options
1739 The readbuf option is not accepted.
1740 retry-time=<gtime>
1742 Instead of restarting a closed connection immediately, this will
1743 cause a delay between the close and the re-open. Also, if the
1744 connect fails, it will not disable itself, it will wait another
1745 retry-time period and try the connect again. See the section on
1746 gtime above. The unit defaults to milliseconds. The default
1747 value is zero.
1748 Direct Allocation
1750 Allocated as a terminal gensio with gdata as a "const char *". That is
1751 the specification of the gensio below it.
1752
1754 connecting = mdns[(options)][,<name>]
1755 This gensio uses mDNS to find a service and then attempts to connect to
1757 it. This can be convenient, it finds the connection type, address, and
1758 port for you, automatically adds telnet and rfc2217 if it's available.
1759 The mDNS name can be set as an option or as the string after the comma
1760 show above.
1761 The name, type, host, and domain strings can be wildcarded in various
1763 ways. See "STRING VALUES FOR WATCHES" in gensio_mdns(3) for details.
1764 Options
1766 The readbuf option is accepted, but if it is not specified the default
1767 value for readbuf will be taken for the sub-gensio is taken. In addi‐
1768 tion to readbuf, the mdns gensio takes the following options:
1769 nostack[=true|false]
1771 By default the mdns gensio will attempt to use the "gensiostack"
1772 text string from the mDNS service. If you don't want it to do
1773 this, setting this option will turn it off.
1774 ignore-v6-link-local[=true|false]
1776 Ignore IPv6 link local addresses, ones starting with "fe80:".
1777 They cause problems on some systems.
1778 mdnstimeout=<gtime>
1780 Set the amount of time to wait for mdns to find the item. See
1781 the "gtime" section for more info on how to set the time. The
1782 default unit is milliseconds, default time is 1 second. The de‐
1783 fault setting for mdnstimeout is not a gtime, it is in integer
1784 in milliseconds. You may also use "timeout" instead of
1785 "mdnstimeout", but not in the default.
1786 name=<mdnsstr>
1788 Set the mdns name to search for. You generally want to set
1789 this, otherwise you will get the first thing that comes up from
1790 the search.
1791 type=<mdnsstr>
1793 Set the mdns type to search for.
1794 domain=<mdnsstr>
1796 Set the mdns domain to search for. You generally don't use
1797 this.
1798 host=<mdnsstr>
1800 Set the mdns host to search for. You generally don't use this.
1801 interface=<num>
1803 Set the network interface number to search on. The default is
1804 -1, which means all interfaces.
1805 nettype=unspec|ipv4|ipv6
1807 The network type to search for. unspec means any type, other‐
1808 wise you can choose to limit it to ipv4 and ipv6.
1809 nodelay[=true|false]
1811 Sets nodelay on the socket. This will be ignored for udp. Note
1812 that the default value for mdns is ignored, if you don't set it
1813 here it will take the default value for the sub-gensio that gets
1814 chosen. laddr=<addr> An address specification to bind to on the
1815 local socket to set the local address.
1816 Direct Allocation
1818 Allocated as a terminal gensio with gdata as a "const char *". That is
1819 the specification of the mdns as a string.
1820
1822 accepter = kiss[(options)]
1823 connecting = kiss[(options)]
1824 A gensio that implements the KISS amateur radio protocol for transfer‐
1826 ring data between a TNC and AX25. See http://www.ax25.net/kiss.aspx
1827 for details. It contains a number of tunable parameters, you probably
1828 shouldn't mess with most of them.
1829 This is a normal packet-oriented interface.
1831 KISS supports multiple TNCs underneath it. To write to a specific TNC,
1833 you must use the auxdata string "tnc:<n>" when writing. If you don't
1834 set that, the TNC is assumed to be zero. On reading, "tnc:<n>" will
1835 always be in one of the auxdata fields. You shouldn't set a TNC larger
1836 than the configured number of TNCs.
1837 There is a 8-bit protocol field in the AX25 frame call the PID. This
1839 is not passed in the data, it is also in the auxdata with the format
1840 "pid:<n>". And to set the pid, pass it in the auxdata on write. If
1841 you don't set the pid, it defaults to 240 (0xf0).
1842 Options
1845 kiss supports the following options:
1846 readbuf=<n>
1848 Sets the maximum packet size that can be read from the TNC. De‐
1849 faults to 256.
1850 writebuf=<n>
1852 Sets the maximum packet size that can be written to the TNC.
1853 Defaults to 256.
1854 tncs=<n>
1856 The number of supported TNCs. Defaults to 1.
1857 server[=yes|no]
1859 Is this a KISS server or client. A client will set the tunable
1860 parameters on the TNC. A server is expected to be a TNC, but
1861 this isn't fully implemented yet as you can't get the tunable
1862 parameters.
1863 setupstr=<string>
1865 Send the given string at startup to set up the device.
1866 setup-delay=<n milliseconds>
1868 Wait for the given number of milliseconds after sending the
1869 setup string before continuing operation.
1870 d710[=yes|no]
1872 If set to yes or just "d710" is given, set the setupstr to a
1873 value for the Kenwood D710 radio. This is the same as doing:
1874 setupstr='xflow on\rhbaud 1200\rkiss on\rrestart\r'
1875 d710-9600[=yes|no]
1877 If set to yes or just "d710-9600" is given, set the setupstr to
1878 a value for the Kenwood D710 radio at 9600 bps. This is the
1879 same as doing: setupstr='xflow on\rhbaud 9600\rkiss
1880 on\rrestart\r'
1881 txdelay=<n>
1883 The KISS txdelay parameter, in milliseconds, rounded to the
1884 nearest power of ten. The maximum values is 2550. Default is
1885 50ms.
1886 persist=<n>
1888 The KISS "P" parameter, ranging from 0-255. I don't know what
1889 this means, the spec isn't clear. You'll have to figure it out
1890 on your own. Default is 63.
1891 slottime=<n>
1893 The KISS slot time parameter, in milliseconds, rounded to the
1894 nearest power of 10. The maximum value is 2550ms, the default
1895 is 100ms.
1896 fullduplex[=yes|no]
1898 Set's full duplex on the connection.
1899 sethardware=<n>
1901 A hardware-specific control value ranging from 0-255. It's
1902 meaning depends on the hardware. By default it is not set.
1903
1905 accepter = ax25[(options)]
1906 connecting = ax25[(options)]
1907 A gensio that implements the AX25 amateur radio protocol for transfer‐
1909 ring data. You would generally run this on top of a KISS gensio. See
1910 http://www.ax25.net for details.
1911 This is a normal packet-oriented interface.
1913 It is also a channel-based implementation. Each AX25 connection to a
1915 remote system is implemented as a channel. You can also have an uncon‐
1916 nected channel if you want to just receive UI frames.
1917 There is no server/client setting on an ax25 gensio. The protocol is
1919 symmetric, so it's not necessary. An ax25 accepter will take the first
1920 connection that comes in and deliver it as a gensio, but after that
1921 there's really no difference.
1922 When running as an accepter, incoming connections will be delivered as
1924 new connections, not new channels. This allows you to use an ax25 gen‐
1925 sio more naturally underneath a server without having to know about
1926 ax25 in the code. For instance, to create a simple AX25 server that
1927 reflects all incoming data, you could create a reflector:
1928 greflector -t kiss,tcp,1234
1930 then you could create the server:
1932 gensiot -i 'echo' --server -a \
1934 'ax25(laddr=test-1),conacc,kiss,tcp,localhost,1234'
1935 then you could connect to it:
1937 gensiot 'ax25(laddr=test-2,addr="0,test-1,test-2"),kiss,tcp,lo‐
1939 calhost,1234'
1940 So to use this, allocate an ax25 gensio. If you want to make a connec‐
1942 tion, you must set the addr to a destination address. By default the
1943 laddr will be set from the addr if the addr is supplied. If you just
1944 want UI frames, you don't need to set an address (more on that later).
1945 Then you open the gensio. An ax25 gensio without an address will just
1946 open immediately and start receiving UI packets as directed. With an
1947 addr set, it will attempt to make a connection. Once that is up (or
1948 fails), the open callback is called.
1949 AX25 Addresses
1951 A gensio AX25 address string is in the form:
1952 [ax25:]tncport,dest[:c|r],src[:c|r][,extra1[:h]
1954 [,extra2[:h][..]]]
1955 tncport is a number from 0-15 specifying which TNC to use. dest and
1957 src and subaddresses specifying the destination and source addresses.
1958 Note that the source address better match an laddr, or the connection
1959 won't work. extra fields are also subaddresses. These are used for
1960 routing (a function that is deprecated and no longer use) and by APRS
1961 for it's own purposes, see the APRS spec for details. The c, r, and h
1962 values are bits in the address that you generally don't care about, ex‐
1963 cept for the h field for APRS.
1964 Subaddresses are in the form
1966 callsign-n
1968 where callsign is a set of alphanumeric digits (a-zA-Z0-9) and n is a
1970 number 0-15. Lower case digits are converted to upper case in the ad‐
1971 dress and not converted back on receipt.
1972 Handling unconnected packets (UI frames)
1974 To receive UI frames, you must enable the GENSIO_CONTROL_ENABLE_OOB
1975 control on the gensio. If you set the value to 1, you will receive UI
1976 frames where the destination matches one of your laddrs. If you set it
1977 to 2, you will receive all UI frames (promiscuous mode). 0 disables
1978 receipt of UI frames.
1979 UI frames are reported with the "oob" in the auxdata, like out of band
1981 data. Note that you must completely handle all the UI frame in the
1982 call. If you don't consume all the data, it will not be called again.
1983 You can have a channel that receives both connected data and UI frames,
1985 but you would generally have a separate channel with no addr set for
1986 receiving UI frames. If you don't set the laddr field, that channel
1987 can only be used for promiscuous mode.
1988 On received packets, the auxdata will contain a field starting with
1990 "addr:" and the rest is the gensio AX25 address in the packet. When
1991 sending a UI frame, you must set "oob" and "addr:" fields in the aux‐
1992 data, with a valid address in the "addr:" field.
1993 Options
1995 Option values for channels are all inherited from the options used to
1996 create the first channel, except for addr (which must be supplied for
1997 each channel if you care) and laddr (which is only used on the first
1998 channel. ax25 supports the following options:
1999 readbuf=<n>
2001 Sets the maximum packet size that can be read. Defaults to 256.
2002 writebuf=<n>
2004 Sets the maximum packet size that can be written. Defaults to
2005 256.
2006 readwindow=<n>
2008 Sets the maximum packet size that can be received and unacked.
2009 Defaults to 7 for extended and 4 for non-extended.
2010 writewindow=<n>
2012 Sets the maximum number of packets that can be sent unacked to
2013 the remote side. Defaults to 7 for extended and 4 for non-ex‐
2014 tended.
2015 extended=<n>
2017 Set the extended mode. Setting it to 1 will enable 7-bit se‐
2018 quence numbers, the connection will first attempt to use 7-bit
2019 sequence number. If that fails, it will fall back to 3-bit se‐
2020 quence numbers.
2021 Setting the value to 2 will enable a non-standard operation that
2023 will add parameter negotiation to the connection startup. Set‐
2024 ting the readbuf, writebuf, readwindow, and writewindow without
2025 extended=2 really isn't very useful as without the negotiation
2026 it will be forced to fall back to the defaults. If extended=2
2027 fails, it will fall back to extended=1.
2028 laddr=<subaddr>[;<subaddr[...]]
2030 Set the addresses the ax25 gensio will receive packets for. Ex‐
2031 cept for promiscuous UI mode, the destination of a packet must
2032 match one of these addresses to be handled. This can only be
2033 set on the accepter or on the first connection and applies to
2034 all channels.
2035 If you do not set this, but addr is set, the laddr will be set
2037 from the source address of addr.
2038 addr=<ax25addr>
2040 Set the address of the remote end of the connection. Packets
2041 will be sent to this address.
2042 crc[=yes|no]
2044 Enable CRC checking. Default is off.
2045 ign_emb_ua[=yes|no]
2047 Some AX.25 stacks do not properly reset themselves when they get
2048 a second SABM (due to a timeout) but they still send a UA. If
2049 you are getting errors about receiving a UA while connected and
2050 the connection hangs, try enabling this option.
2051 srt=<n>
2053 The initial smoothed round trip time for the connection, in mil‐
2054 liseconds. See the spec for details, you probably don't need to
2055 mess with it. Note that this value you set here is multiplied
2056 by the number of digipeaters between the source and the destina‐
2057 tion for the actual value. Defaults to 1500.
2058 t2=<n> The timer 2 value for the connection, in milliseconds. See the
2060 spec for details, you probably don't need to mess with it. De‐
2061 faults to 2 seconds.
2062 t3=<n> The timer 3 value for the connection, in milliseconds. See the
2064 spec for details, you probably don't need to mess with it. De‐
2065 faults to 300 seconds.
2066 retries=<n>
2068 Number of retries on a send before giving up and dropping the
2069 connection. See the spec for details, you probably don't need
2070 to mess with it. Defaults to 10.
2071
2073 accepter = xlt[(options)]
2074 connecting = xlt[(options)]
2075 A gensio that translates characters. This is primarily for translating
2077 line feeds and carraige returns, but may eventually be extended to do
2078 string substitutions and such.
2079 The readbuf option is not available in this gensio.
2081 Options
2083 in=<n>:<m>
2084 Translate character n (a number, 0xnn for hex, 0nnn for octal,
2085 or nn for decimal) to character m on data read from the gensio.
2086 out=<n>:<m>
2088 Like in, but translate character n to character m on data writ‐
2089 ten to the gensio.
2090 nlcr Translate new lines to carraige returns on data read from the
2092 gensio, and carraige returns to new lines on data written to the
2093 gensio.
2094 crnl Translate carraige returns to new lines on data read from the
2096 gensio, and new lines to carraige returns on data written to the
2097 gensio.
2098
2100 connecting = keepopen[(options)]
2101 A filter gensio that makes it appear to the user that the gensios below
2103 it are always open. If the gensio below it goes away, this will at‐
2104 tempt to re-open it periodically.
2105 The readbuf option is not available in this gensio.
2107 Options
2109 retry-time=<gtime>
2110 Set the retry interval. See the section on gtime for detail on
2111 this. Defaults to milliseconds it no unit given. The default
2112 is 1 second.
2113 discard-badwrites[=yes|no]
2115 Normally this gensio will flow-control the upper layer when the
2116 lower gensio is not open. If you enable this, it will just
2117 throw write data away if the lower gensio is not open.
2118
2120 connecting = script[(options)] accepting = script[(options)]
2121 A filter gensio that allows an external program to interact with the
2123 child gensio before reporting that it is open. The external program
2124 runs with its stdio connected to the child of this gensio, so writes
2125 from the external program get written to the child and reads from the
2126 child get written to the external program's stdin. If the program re‐
2127 turns without error, the open for this gensio succeeds. If the program
2128 returns an error, GE_LOCALCLOSED is reported as an open error.
2129 The readbuf option is not available in this gensio.
2131 Options
2133 script=<string>
2134 Run the program given in the string as the external program.
2135 This is equivalent to doing: gensio=stdio(noredir-
2136 stderr),<string>, it just a shortcut.
2137 gensio=<string>
2139 Instead of running a program, run the given gensio. When the
2140 gensio closes, handle an error. If the gensio supported getting
2141 an error code, that is done.
2142
2144 connecting = sound[(options)],<device>
2145 The sound gensio provides access to sound devices on the platform.
2147 It's an unusual gensio in many respects. It's not terribly useful for
2148 normal streaming operation. It is a streaming operation, though, so it
2149 still fits. But to avoid underruns and overruns, the stream has to be
2150 continuously supplied or consumed.
2151 The stream consists of bytes of binary data in the host's byte order.
2153 If the low-level sound interface uses a different byte order, it is
2154 converted to the host's order in the gensio. The gensio can also con‐
2155 vert data types. If you ask for a float format and the low level
2156 driver can only do integers, the gensio will convert for you. Each
2157 data item (byte, int16, etc) is called a sample. So the driver has a
2158 user format (what the user sees) and a PCM format (what the driver
2159 uses).
2160 A stream has a number of channels, at least one. Stereo, for instance,
2162 has two channels. A frame consists of samples for all channels.
2163 Frames are always interleaved; the individual channels appear as suc‐
2164 cessive data items in the stream. So in stereo, sample1 is channel 1
2165 in the first frame, sample2 is channel 2 in the first frame, sample 3
2166 is channel 1 in the second frame, etc.
2167 A buffer is a set of frames. A buffers's size is specified in frames,
2169 not bytes. Reads are always provided in buffer size chunks. If you do
2170 not comsume all the data in a buffer, it will give you the rest of the
2171 buffer the next read, until the buffer is consumed. Writes can be
2172 written in any size, but it's generally most efficient to always write
2173 buffer sized chunks.
2174 A number of buffers can also be specified. You generally want a large
2176 enough number that data can be smoothly written into the device without
2177 delay if the program lags a bit, but too large and you end up with lag
2178 if you want to change the data being written..
2179 A sound gensio may have input, output, or both. You specify which you
2181 want by setting the number of channels to a non-zero value. Most of
2182 the parameters can be prefixed with "in" or "out" to specify that the
2183 parameter only applies to the input and output device. If you don't
2184 have that prefix, it will apply to both the input and output. Note
2185 that the input and output streams are completely independent; they can
2186 have different type, format, rates, etc.
2187 Different sound interfaces are available on platforms. For Linux, alsa
2189 and file interfaces are available, and possibly portaudio, depending on
2190 how it is compiled. On Windows, win and file interfaces are available
2191 and possibly portaudio. On Macos portaudio and file are available.
2192 The device is specified on the command line. The name is system-depen‐
2194 dent. For alsa, the name must match exactly. You can use "aplay -L"
2195 or "arecord -L" to list input and output devices available. Or you can
2196 use the "gsound -L" program.
2197 For Windows and portaudio, the name just has to match part of the de‐
2199 vice's name. Windows names always start with a number. So, for in‐
2200 stance, if the output of "gsound -L" on your windows platform is:
2201 0:Microphone (Realtek(R) Audio) input,inchans=2
2203 0:Speakers (Realtek(R) Audio) output,outchans=2
2204 The numbers at the beginning are subject to change, so it's better to
2206 use part of the name like "Realtek", which will match both input and
2207 output. It will not select an output-only device for input or an in‐
2208 put-only device for output.
2209 On MacOS with portaudio you might see:
2211 0:USB Audio CODEC output,outchans=2
2213 1:USB Audio CODEC input,inchans=2
2214 2:Mac mini Speakers output,outchans=2 where you could use
2215 "USB Audio" for the name.
2216 For file type, the device name is a filename; data is streamed
2218 to/from the file in the PCM format. If the filename is "-",
2219 then stdio is used instead of opening a file.
2220 The readbuf option is not available in this gensio, obviously.
2222 Options
2224 <samplerate>-<channels>-<format>
2225 For simple applications, the sound gensio takes a compact and
2226 simple format as an option. It specifies those things for both
2227 the input and output channel. So, for instance,
2228 "sound(44100-2-float)" would be CD-rate two channel using float‐
2229 ing point numbers.
2230 list[=yes|no]
2232 Instead of opening a sound device, the gensio will provide data
2233 about the various sound interfaces available. Every other op‐
2234 tion but "type" is ignored. If "type" is supplied, list the in‐
2235 terfaces for that type. If "type" is not supplied, list the in‐
2236 terfaces for the default one.
2237 The data will be a string with each interfaces separated by a
2239 newline. There will be an interface name, a tab, and the inter‐
2240 face specification.
2241 outdev=<str>
2243 If the output device has a different name than the input device,
2244 it must be specified separately.
2245 inbufsize=<n>, outbufsize=<n>, bufsize=<n>
2247 Specify the buffer size, in samples. This defaults to 1024.
2248 innbufs=<n>, outnbufs=<n>, nbufs=<n>
2250 Specify the number of buffers to use. This may or may not be
2251 used depending on the interface type. It's ignored for file,
2252 for instance. Defaults to 100.
2253 chans=<n>, inchans=<n>, outchans=<n>
2255 Set the number of input and output channels. One of these must
2256 be specified, if you say chans it will set both the input and
2257 output number of channels. If you only specify in or out, the
2258 other is not enabled.
2259 inrate=<n>, outrate=<n>, rate=<n>
2261 The sample rate, in samples per second. Common ones are 44100
2262 (CD), 48000 (DAT).
2263 intype=<n>, outtype=<n>, type=<n>
2265 Set the interface type. Must be "alsa" (Linux only), "win"
2266 (Windows only), "portaudio" (MacOS, generally) or "file". If
2267 not set, this default to alsa on Linux, win on Windows, and por‐
2268 taudio no Macos.
2269 informat=<n>, outformat=<n>, format=<n>
2271 Set the type of data to supply to the user. This is one of:
2272 float64, float, s32, s32, s16, or s8. User samples are always
2273 signed and either floating point or integer. Floating point is
2274 normalized from -1.0 to 1.0. You must specify this.
2275 inpformat=<n>, outpformat=<n>, pformat=<n>
2277 The data format on the PCM size. You have all the data formats
2278 specified for format above. The integer ones can be prefixed
2279 with "u" instead of "s" to make them unsigned (like u16), and
2280 all may be suffixed with "le" or "be" to make them little or big
2281 endian (like float64_le). If you do not specify this, the gen‐
2282 sio will attempt the same format as the user format. If that
2283 doesn't work, it will attempt to pick the best matching format
2284 and convert.
2285
2287 connecting = afskmcm[(options)]
2288 A filter gensio that sits on top of the sound gensio and implements an
2290 Audio Frequency Shift Keying modem, like is used on AX.25 amateur ra‐
2291 dio. It must sit on top of a sound gensio. Or, more accurately a gen‐
2292 sio that implements the GENSIO_CONTROL_IN_BUFSIZE, GENSIO_CON‐
2293 TROL_OUT_BUFSIZE, GENSIO_CONTROL_IN_FORMAT, and GENSIO_CONTROL_OUT_FOR‐
2294 MAT controls.
2295 Note that the sound gensio must supply a float user format.
2297 Keying the Transmitter
2299 By default, afskmcm will not do anything specific to turn the transmit‐
2300 ter on and off. In this case the keying must be VOX, like a SignaLink.
2301 If you need some other way to key the transmitter, afskmcm provide a
2303 key option. This create a gensio that is used to turn the transmitter
2304 on and off. Different types of keying options exist, specified by key‐
2305 type.
2306 If keytype is rw, which is the default, then it will open the key gen‐
2308 sio and send the keyon string and the keyoff string for this purpose.
2309 If keytype is one of rts, rtsinv, dts, dtsinv then it will open the key
2311 gensio as a serial device and set the RTS/DTR lines appropriately. The
2312 "inv" options mean that setting the line "on" will turn off the trans‐
2313 mitter, setting it "off" will enable the transmitter.
2314 You could do
2316 keytype=rts,key="serialdev,/dev/serial/by-
2318 path/pci-0000:00:14.0-usb-0:4.4.2.4.2:1.0-port0"
2319 to set up an RTS-base serial control on a port.
2321 There is a cm108 soundcard GPIO gensio available. See that gensio for
2323 details, but you would generally do something like:
2324 keytype=cm108
2326 and this gensio will fetch the sound card identifier from the sound de‐
2328 vice and use the cm108gpio gensio to key the device. If you have some
2329 special setup where the default won't work, you can use
2330 keytype=rw,key="cm108gpio,<dev>"
2332 See the cm108gpio gensio docs for details.
2334 If you need something more sophisicated, you could create your own pro‐
2336 gram to do the keying and add:
2337 key="stdio,mykeyprog --parm1 --parm2",keyon="1",keyoff="0"
2339 to your afskmdm option and it would run the mykeyprog program when
2341 opened. When it needed to transmit, it would write a "1" (no newline
2342 or anything sent) to the stdin of the program. When the transmission
2343 was complete, it would write a "0". Not numbers, these are "0" and "1"
2344 characters.
2345 If you program sends output to stderr, you probably want to add stderr-
2347 to-stdout to the stdin so the stderr buffers doesn't fill up and block
2348 the program. Then stderr data will be ignored.
2349 You can use rigctld with this. I have the following rigctld setup on
2351 my system:
2352 rigctld -m 1022 -r /dev/ttyUSB0 -s 4800 -P CM108 -p /dev/hidraw1
2354 And I use the following in my configuration:
2356 afskmdm(key="tcp,localhost,4532",keyon="T 1\n",keyoff="T 0\n")
2358 You have to be careful of the quoting here, as the key specification
2360 must be in quotes because it will have commas. Notice the use of "\n"
2361 in the strings for a new line. Normal C "\" escape sequences are han‐
2362 dled. Also, since the defaults for keyon and keyoff are what's given
2363 above, you don't have to specify those here.
2364 Anything read in from the key gensio is ignored.
2366 Options
2368 readbuf=<n>
2369 Sets the maximum packet size that can be read. Defaults to 256.
2370 writebuf=<n>
2372 Sets the maximum packet size that can be written. Defaults to
2373 256.
2374 nchans=<n>, in_nchans=<n>, out_nchans=<n>
2376 Specify how many channels are coming from/going to the sound
2377 gensio. The sound gensio interleaves the sound for multiple
2378 channels. By default this is fetched from the sound gensio.
2379 chan=<n>, in_chan=<n>, out_chan=<n>
2381 Which specific channel to use. One one channel is used for in‐
2382 put sound and output sound, the others are ignored or filled
2383 with zeros. By default this is zero.
2384 out_chans=<n>
2386 Specify a bitmask of which channels to output sound on. The
2387 same sound will be output for all selected channel. So n=1 will
2388 only output on channel 0, n=3 will output on channels 0 and 1,
2389 etc. By default only channel 0 is output on.
2390 samplerate=<n>, in_samplerate=<n>, out_samplerate=<n>
2392 The sample rate, samples per second, of the data. By default
2393 this is fetched from the sound gensio.
2394 checkax25[=true|false]
2396 Check that the packet is a valid AX.25 packet, that it has valid
2397 AX25 length and address. Normally the AX.25 layer does this,
2398 but this can be used when testing without an AX.25 layer to re‐
2399 ject bad packets. Default to false. Note that if you set crc
2400 to false, this option will not work.
2401 crc[=true|false]
2403 Check and send CRCs on packets. Normally you want the afskmdm
2404 code to do this, but can be useful for testing. Default to
2405 true.
2406 wmsgs=<n>
2408 The number of working messages at the same time. If the bit
2409 fails the certainty test (see below), for every current working
2410 message, two are created, one with each bit possibility, up to
2411 the count specified in this option. These are kept until a mes‐
2412 sage is correctly received (with CRC) or the series of bits is
2413 not valid.
2414 This way, if wmsg is 2^n, a message can be correctly decoded if
2416 up to n bits are wrong. So it's sort of an error correction
2417 code without a code. Defaults to 32.
2418 wmsg-extra=<n>
2420 Sets the number of extra amplification levels for the mark and
2421 space frequencies to try. If set to 1, an extra complete detec‐
2422 tion is done with the space frequency amplified by 3db, then the
2423 mark frequency amplified by 3db. If set to 2, it will do this
2424 with3db then 6db, and so on. This can help compensate for fil‐
2425 tering on the different frequencies. Defaults to 1.
2426 min-certainty=<float>
2428 A floating point number that specifies the minimum certainty
2429 above which a bit is considered good. The ratio of the signal
2430 power for the mark and space frequencies is calculated as the
2431 certainty. If that certainty is below min-certainty, it does
2432 the wmsgs procedure above. Defaults to 2.0.
2433 filttype=[fir|iir|none]
2435 A 2nd-order low-pass Butterworth IIR filter or a low-pass FIR
2436 filter is implemented on the input. This selects which filter,
2437 or no filter. The IIR filter doesn't use very much CPU, the FIR
2438 filter uses a lot of CPU at higher sample rates. This is mostly
2439 for experimentation. The default is IIR for sample rates above
2440 30000Hz and FIR for lower sample rates. Lower sample rates
2441 don't work well with the IIR filter, but there's not much dif‐
2442 ference at higher sample rates.
2443 lpcutoff=<n>
2445 This sets the cutoff frequency for the input filter. Setting it
2446 to zero disables it. The default is 2500Hz.
2447 trfreq=<n>
2449 This sets the transition frequency width for the FIR filter.
2450 This is ignored for the IIR filter. The default is 500Hz.
2451 Smaller numbers make a sharper cutoff but result in more CPU be‐
2452 ing used.
2453 tx-preamble=<n>
2455 The time in milliseconds at the beginning of a message that is
2456 just flags. This lets the receiver turn on and the other end
2457 synchronize. Default is 300.
2458 tx-tail=<n>
2460 The time in milliseconds at the end of the message that is just
2461 flags. Default is 100.
2462 tx-predelay=<n>
2464 The amount of time to wait after another sender has finished
2465 sending a message before the transmit is started. Default is
2466 500ms.
2467 volume=<float>
2469 Sets the transmit volume, from 0.0-1.0. Values above 1.0 will
2470 clip. Default is .75.
2471 key=<gensio string>
2473 This creates a gensio that will be used to key the transmitter on and
2475 off. See the discussion above on keying for more details. key‐
2476 type=rw|rts|rtsinv|dtr|dtrinv|cm108 This sets the type of keying
2477 done, per the discussion above. This is rw by default.
2478 keyon=<string>, keyoff=<string>
2479 The strings to send to the key gensio to turn the transmitter on and
2481 off. For keytype=rw only. The default to "T 10 and "T 00 by
2482 default, which is what rigctld takes. keybit=<n>
2483 This sets the bit number to use on the cm108 keytype. This is 3 by
2485 default. full-duplex[=yes|no]
2486 Treat the read and write streams as completely independent. Transmit
2488 does not check if something is being received before sending,
2489 all sends just start immediately.
2490
2492 connecting = cm108gpio[(options)],<soundcard>
2493 This allows a GPIO on a cm108 soundcard to be controlled. Some radio
2495 sound card devices use one of these bits to key the transmitter. Any
2496 write with a '1' in it will enable the GPIO, any write with a '0' in it
2497 will disable the GPIO. There are 8 available GPIOs, ranging 1-8, most
2498 devices use 3.
2499 For Linux, <soundcard> is the soundcard number or device name given to
2501 open the sound device, generally what's right after the ":", like
2502 "plughw,1,0" would be "1". If it was "plughw,Device,0", it would be
2503 "Device".
2504 For Windows, <soundcard> is the same thing you put for the soundcard,
2506 like "USB PnP Sound", or whatever "gsound -L" returns for your device.
2507 The readbuf option is not available in this gensio.
2509 Options
2511 bit=1-8
2512 The bit number to control. The default is 3.
2513
2515 Unlike normal file descriptors, when you fork with a gensio, you now
2516 have two unassociated copies of the gensios. So if you do operations
2517 on one, it might mess up the other. Even a close might cause issues,
2518 if you close an SSL connection, it sends data to the other end to close
2519 the connection, even if the other fork doesn't want that.
2520 To avoid issues with this, you should generally first make sure that no
2522 thread is in a wait, service call, or any type of thing that would ex‐
2523 amine file descriptors or timers and act on them. This is very impor‐
2524 tant, and you must do it before you fork.
2525 Then after you fork, you should call:
2527 gensio_disable(io)
2529 on all the gensios that fork is not using, then free the gensios.
2531 Don't use close, use free. Then you should call:
2532 gensio_acc_disable(acc)
2534 on every gensio accepter that fork is not using, then free them. If a
2536 connection is in progress and has not been reported to the user, it
2537 will be disabled then closed.
2538 You cannot share a gensio between two different processes. If a gensio
2540 is used in one fork, it must be disabled and closed in the other fork.
2541 Another issue with forking on Linux is epoll. An epoll fd is not du‐
2543 plicated on a fork, both forks get the same epoll fd. If you close the
2544 epoll fd in one for, it will close it for the other. To avoid this is‐
2545 sue, the os handler has a handle_fork() function that you must call af‐
2546 ter a fork in the new fork (not the old one). It will handle any
2547 cleanup required after the fork. Other systems may require other
2548 cleanups after a fork, so you should always call this after a fork.
2549
2551 gensiot(1), sctp(7), udp(7), tcp(7), unix(7)
2552
2554 None.
2555
2557 Corey Minyard <minyard@acm.org>
2558Specifying a gensio 01/02/19 gensio(5)