kerberos

title: kerberos(7)

summary: Overview of using Kerberos

text:
# kerberos(7)

## NAME
kerberos - Overview of using Kerberos

## DESCRIPTION
The Kerberos system authenticates individual users in a network environment. After authenticating yourself to Kerberos, you can use Kerberos-enabled programs without having to present passwords or certificates to those programs.

If you receive the following response from kinit:

kinit: Client not found in Kerberos database while getting initial credentials

you haven't been registered as a Kerberos user. See your system administrator.

A Kerberos name usually contains three parts. The first is the primary, which is usually a user's or service's name. The second is the instance, which in the case of a user is usually null. Some users may have privileged instances, however, such as root or admin. In the case of a service, the instance is the fully qualified name of the machine on which it runs; i.e. there can be an ssh service running on the machine ABC (ssh/ABC@REALM), which is different from the ssh service running on the machine XYZ (ssh/XYZ@REALM). The third part of a Kerberos name is the realm. The realm corresponds to the Kerberos service providing authentication for the principal. Realms are conventionally all-uppercase, and often match the end of hostnames in the realm (for instance, host01.example.com might be in realm EXAMPLE.COM).

When writing a Kerberos name, the principal name is separated from the instance (if not null) by a slash, and the realm (if not the local realm) follows, preceded by an "@" sign. The following are examples of valid Kerberos names:

```
david
jennifer/admin
joeuser@BLEEP.COM
cbrown/root@FUBAR.ORG
```

When you authenticate yourself with Kerberos you get an initial Kerberos ticket. (A Kerberos ticket is an encrypted protocol message that provides authentication.) Kerberos uses this ticket for network utilities such as ssh. The ticket transactions are done transparently, so you don't have to worry about their management.

Note, however, that tickets expire. Administrators may configure more privileged tickets, such as those with service or instance of root or admin, to expire in a few minutes, while tickets that carry more ordinary privileges may be good for several hours or a day. If your login session extends beyond the time limit, you will have to re-authenticate yourself to Kerberos to get new tickets using the kinit command.

Some tickets are renewable beyond their initial lifetime. This means that kinit -R can extend their lifetime without requiring you to re-authenticate.

If you wish to delete your local tickets, use the kdestroy command.

Kerberos tickets can be forwarded. In order to forward tickets, you must request forwardable tickets when you kinit. Once you have forwardable tickets, most Kerberos programs have a command line option to forward them to the remote host. This can be useful for, e.g., running kinit on your local machine and then sshing into another to do work. Note that this should not be done on untrusted machines since they will then have your tickets.

## ENVIRONMENT VARIABLES
Several environment variables affect the operation of Kerberos-enabled programs. These include:

KRB5CCNAME

Default name for the credentials cache file, in the form TYPE:residual. The type of the default cache may determine the availability of a cache collection. FILE is not a collection type; KEYRING, DIR, and KCM are. If not set, the value of default_ccache_name from configuration files (see KRB5_CONFIG) will be used. If that is also not set, the default type is FILE, and the residual is the path /tmp/krb5cc_*uid*, where uid is the decimal user ID of the user.

KRB5_KTNAME

Specifies the location of the default keytab file, in the form TYPE:residual. If no type is present, the FILE type is assumed and residual is the pathname of the keytab file. If unset, FILE:/etc/krb5.keytab will be used.

KRB5_CONFIG

Specifies the location of the Kerberos configuration file. The default is /etc/krb5.conf. Multiple filenames can be specified, separated by a colon; all files which are present will be read.

KRB5_KDC_PROFILE

Specifies the location of the KDC configuration file, which contains additional configuration directives for the Key Distribution Center daemon and associated programs. The default is /var/lib/kerberos/krb5kdc/kdc.conf.

KRB5RCACHENAME

(New in release 1.18) Specifies the location of the default replay cache, in the form type:residual. The file2 type with a pathname residual specifies a replay cache file in the version-2 format in the specified location. The none type (residual is ignored) disables the replay cache. The dfl type (residual is ignored) indicates the default, which uses a file2 replay cache in a temporary directory. The default is dfl:.

KRB5RCACHETYPE

Specifies the type of the default replay cache, if KRB5RCACHENAME is unspecified. No residual can be specified, so none and dfl are the only useful types.

KRB5RCACHEDIR

Specifies the directory used by the dfl replay cache type. The default is the value of the TMPDIR environment variable, or /var/tmp if TMPDIR is not set.

KRB5_TRACE

Specifies a filename to write trace log output to. Trace logs can help illuminate decisions made internally by the Kerberos libraries. For example, env KRB5_TRACE=/dev/stderr kinit would send tracing information for kinit to /dev/stderr. The default is not to write trace log output anywhere.

KRB5_CLIENT_KTNAME

Default client keytab file name. If unset, FILE:/var/lib/kerberos/krb5/user/%{euid}/client.keytab will be used).

KPROP_PORT

kprop port to use. Defaults to 754.

GSS_MECH_CONFIG

Specifies a filename containing GSSAPI mechanism module configuration. The default is to read /etc/gss/mech and files with a .conf suffix within the directory /etc/gss/mech.d.

Most environment variables are disabled for certain programs, such as login system programs and setuid programs, which are designed to be secure when run within an untrusted process environment.

## SEE ALSO
kdestroy, kinit, klist, kswitch, kpasswd, ksu, krb5.conf, kdc.conf, kadmin, kadmind, kdb5_util, krb5kdc

## AUTHORS

```
Steve Miller, MIT Project Athena/Digital Equipment Corporation
Clifford Neuman, MIT Project Athena
Greg Hudson, MIT Kerberos Consortium
Robbie Harwood, Red Hat, Inc.
```

## HISTORY
The MIT Kerberos 5 implementation was developed at MIT, with contributions from many outside parties. It is currently maintained by the MIT Kerberos Consortium.

## RESTRICTIONS
Copyright 1985, 1986, 1989-1996, 2002, 2011, 2018 Masachusetts Institute of Technology

## AUTHOR
MIT

## COPYRIGHT
1985-2026, MIT


sctp

package: liblksctp-devel

title: sctp(7)

summary: SCTP protocol.

text:
# sctp(7)

## NAME
sctp - SCTP protocol.

## SYNOPSIS

```
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/sctp.h>

sctp_socket = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
sctp_socket = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
```

## DESCRIPTION
This is an implementation of the SCTP protocol as defined in RFC2960 and RFC3309. It is a message oriented, reliable transport protocol with direct support for multihoming that runs on top of ip(7), and supports both v4 and v6 versions.

Like TCP, SCTP provides reliable, connection oriented data delivery with congestion control. Unlike TCP, SCTP also provides message boundary preservation, ordered and unordered message delivery, multi-streaming and multi-homing. Detection of data corruption, loss of data and duplication of data is achieved by using checksums and sequence numbers. A selective retransmission mechanism is applied to correct loss or corruption of data.

This implementation supports a mapping of SCTP into sockets API as defined in the draft-ietf-tsvwg-sctpsocket-10.txt(Sockets API extensions for SCTP). Two styles of interfaces are supported.

A one-to-many style interface with 1 to MANY relationship between socket and associations where the outbound association setup is implicit. The syntax of a one-to-many style socket() call is

sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);

A typical server in this style uses the following socket calls in sequence to prepare an endpoint for servicing requests.

1. socket()

2. bind()

3. listen()

4. recvmsg()

5. sendmsg()

6. close()

A typical client uses the following calls in sequence to setup an association with a server to request services.

1. socket()

2. sendmsg()

3. recvmsg()

4. close()

A one-to-one style interface with a 1 to 1 relationship between socket and association which enables existing TCP applications to be ported to SCTP with very little effort. The syntax of a one-to-one style socket() call is

sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);

A typical server in one-to-one style uses the following system call sequence to prepare an SCTP endpoint for servicing requests:

1. socket()

2. bind()

3. listen()

4. accept()

The accept() call blocks until a new association is set up. It returns with a new socket descriptor. The server then uses the new socket descriptor to communicate with the client, using recv() and send() calls to get requests and send back responses. Then it calls

5. close()

to terminate the association. A typical client uses the following system call sequence to setup an association with a server to request services:

1. socket()

2. connect()

After returning from connect(), the client uses send() and recv() calls to send out requests and receive responses from the server. The client calls

3. close()

to terminate this association when done.

## ADDRESS FORMATS
SCTP is built on top of IP (see ip(7)). The address formats defined by ip(7) apply to SCTP. SCTP only supports point-to-point communication; broadcasting and multicasting are not supported.

## SYSCTLS
These variables can be accessed by the /proc/sys/net/sctp/* files or with the sysctl(2) interface. In addition, most IP sysctls also apply to SCTP. See ip(7).

Please check kernel documentation for this, at Documentation/networking/ip-sysctl.txt.

## STATISTICS
These variables can be accessed by the /proc/net/sctp/* files.

assocs

Displays the following information about the active associations. assoc ptr, sock ptr, socket style, sock state, association state, hash bucket, association id, bytes in transmit queue, bytes in receive queue, user id, inode, local port, remote port, local addresses and remote addresses.

eps

Displays the following information about the active endpoints. endpoint ptr, sock ptr, socket style, sock state, hash bucket, local port, user id, inode and local addresses.

snmp

Displays the following statistics related to SCTP states, packets and chunks.

SctpCurrEstab

The number of associations for which the current state is either ESTABLISHED, SHUTDOWN-RECEIVED or SHUTDOWN-PENDING.

SctpActiveEstabs

The number of times that associations have made a direct transition to the ESTABLISHED state from the COOKIE-ECHOED state. The upper layer initiated the association attempt.

SctpPassiveEstabs

The number of times that associations have made a direct transition to the ESTABLISHED state from the CLOSED state. The remote endpoint initiated the association attempt.

SctpAborteds

The number of times that associations have made a direct transition to the CLOSED state from any state using the primitive 'ABORT'. Ungraceful termination of the association.

SctpShutdowns

The number of times that associations have made a direct transition to the CLOSED state from either the SHUTDOWN-SENT state or the SHUTDOWN-ACK-SENT state. Graceful termination of the association.

SctpOutOfBlues

The number of out of the blue packets received by the host. An out of the blue packet is an SCTP packet correctly formed, including the proper checksum, but for which the receiver was unable to identify an appropriate association.

SctpChecksumErrors

The number of SCTP packets received with an invalid checksum.

SctpOutCtrlChunks

The number of SCTP control chunks sent (retransmissions are not included). Control chunks are those chunks different from DATA.

SctpOutOrderChunks

The number of SCTP ordered data chunks sent (retransmissions are not included).

SctpOutUnorderChunks

The number of SCTP unordered chunks(data chunks in which the U bit is set to 1) sent (retransmissions are not included).

SctpInCtrlChunks

The number of SCTP control chunks received (no duplicate chunks included).

SctpInOrderChunks

The number of SCTP ordered data chunks received (no duplicate chunks included).

SctpInUnorderChunks

The number of SCTP unordered chunks(data chunks in which the U bit is set to 1) received (no duplicate chunks included).

SctpFragUsrMsgs

The number of user messages that have to be fragmented because of the MTU.

SctpReasmUsrMsgs

The number of user messages reassembled, after conversion into DATA chunks.

SctpOutSCTPPacks

The number of SCTP packets sent. Retransmitted DATA chunks are included.

SctpInSCTPPacks

The number of SCTP packets received. Duplicates are included.

## SOCKET OPTIONS
To set or get a SCTP socket option, call getsockopt(2) to read or setsockopt(2) to write the option with the option level argument set to SOL_SCTP.

SCTP_RTOINFO.

This option is used to get or set the protocol parameters used to initialize and bound retransmission timeout(RTO). The structure sctp_rtoinfo defined in /usr/include/netinet/sctp.h is used to access and modify these parameters.

SCTP_ASSOCINFO

This option is used to both examine and set various association and endpoint parameters. The structure sctp_assocparams defined in /usr/include/netinet/sctp.h is used to access and modify these parameters.

SCTP_INITMSG

This option is used to get or set the protocol parameters for the default association initialization. The structure sctp_initmsg defined in /usr/include/netinet/sctp.h is used to access and modify these parameters. Setting initialization parameters is effective only on an unconnected socket (for one-to-many style sockets only future associations are effected by the change). With one-to-one style sockets, this option is inherited by sockets derived from a listener socket.

SCTP_NODELAY

Turn on/off any Nagle-like algorithm. This means that packets are generally sent as soon as possible and no unnecessary delays are introduced, at the cost of more packets in the network. Expects an integer boolean flag.

SCTP_AUTOCLOSE

This socket option is applicable to the one-to-many style socket only. When set it will cause associations that are idle for more than the specified number of seconds to automatically close. An association being idle is defined an association that has NOT sent or received user data. The special value of 0 indicates that no automatic close of any associations should be performed. The option expects an integer defining the number of seconds of idle time before an association is closed.

SCTP_SET_PEER_PRIMARY_ADDR

Requests that the peer mark the enclosed address as the association primary. The enclosed address must be one of the association's locally bound addresses. The structure sctp_setpeerprim defined in /usr/include/netinet/sctp.h is used to make a set peer primary request.

SCTP_PRIMARY_ADDR

Requests that the local SCTP stack use the enclosed peer address as the association primary. The enclosed address must be one of the association peer's addresses. The structure sctp_prim defined in /usr/include/netinet/sctp.h is used to make a get/set primary request.

SCTP_DISABLE_FRAGMENTS

This option is a on/off flag and is passed an integer where a non-zero is on and a zero is off. If enabled no SCTP message fragmentation will be performed. Instead if a message being sent exceeds the current PMTU size, the message will NOT be sent and an error will be indicated to the user.

SCTP_PEER_ADDR_PARAMS

Using this option, applications can enable or disable heartbeats for any peer address of an association, modify an address's heartbeat interval, force a heartbeat to be sent immediately, and adjust the address's maximum number of retransmissions sent before an address is considered unreachable. The structure sctp_paddrparams defined in /usr/include/netinet/sctp.h is used to access and modify an address's parameters.

SCTP_DEFAULT_SEND_PARAM

Applications that wish to use the sendto() system call may wish to specify a default set of parameters that would normally be supplied through the inclusion of ancillary data. This socket option allows such an application to set the default sctp_sndrcvinfo structure. The application that wishes to use this socket option simply passes in to this call the sctp_sndrcvinfo structure defined in /usr/include/netinet/sctp.h. The input parameters accepted by this call include sinfo_stream, sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive. The user must set the sinfo_assoc_id field to identify the association to affect if the caller is using the one-to-many style.

SCTP_EVENTS

This socket option is used to specify various notifications and ancillary data the user wishes to receive. The structure sctp_event_subscribe defined in /usr/include/netinet/sctp.h is used to access or modify the events of interest to the user.

SCTP_I_WANT_MAPPED_V4_ADDR

This socket option is a boolean flag which turns on or off mapped V4 addresses. If this option is turned on and the socket is type PF_INET6, then IPv4 addresses will be mapped to V6 representation. If this option is turned off, then no mapping will be done of V4 addresses and a user will receive both PF_INET6 and PF_INET type addresses on the socket. By default this option is turned on and expects an integer to be passed where non-zero turns on the option and zero turns off the option.

SCTP_MAXSEG

This socket option specifies the maximum size to put in any outgoing SCTP DATA chunk. If a message is larger than this size it will be fragmented by SCTP into the specified size. Note that the underlying SCTP implementation may fragment into smaller sized chunks when the PMTU of the underlying association is smaller than the value set by the user. The option expects an integer. The default value for this option is 0 which indicates the user is NOT limiting fragmentation and only the PMTU will effect SCTP's choice of DATA chunk size.

SCTP_STATUS

Applications can retrieve current status information about an association, including association state, peer receiver window size, number of unacked data chunks, and number of data chunks pending receipt. This information is read-only. The structure sctp_status defined in /usr/include/netinet/sctp.h is used to access this information.

SCTP_GET_PEER_ADDR_INFO

Applications can retrieve information about a specific peer address of an association, including its reachability state, congestion window, and retransmission timer values. This information is read-only. The structure sctp_paddrinfo defined in /usr/include/netinet/sctp.h is used to access this information.

SCTP_GET_ASSOC_STATS

Applications can retrieve current statistics about an association, including SACKs sent and received, SCTP packets sent and received. The complete list can be found in /usr/include/netinet/sctp.h in struct sctp_assoc_stats.

## AUTHORS
Sridhar Samudrala <sri@us.ibm.com>

## SEE ALSO
socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), connect(2), sendmsg(2), recvmsg(2), sysctl(2), getsockopt(2), sctp_bindx(3), sctp_connectx(3), sctp_sendmsg(3), sctp_sendv(3), sctp_send(3), sctp_recvmsg(3), sctp_recvv(3), sctp_peeloff(3), sctp_getladdrs(3), sctp_getpaddrs(3), sctp_opt_info(3).

RFC2960, RFC3309 for the SCTP specification.

branch: sisyphus


libmd

package: libmd-devel

title: libmd(7)

text:
# libmd(7)

## NAME
libmd — Message Digest functions from BSD systems

## DESCRIPTION
The libmd library provides message digest functions found on BSD systems either on their libc or libmd libraries and lacking on others like GNU systems, thus making it easier to port projects with strong BSD origins, without needing to embed the same code over and over again on each project.

The library provides a compatibility interface for the Aladding Enterprises MD5 implementation, but the interface is not exposed by default to avoid polluting the namespace. The LIBMD_MD5_ALADDIN pre-processor variable needs to be defined to expose this interface.

The library provides a pkgconf(1) entry named libmd.

## HEADERS
The libmd library provides compatibility with various BSD headers and interfaces.

The following headers are provided for compatibility with NetBSD and OpenBSD.

<md2.h>

<md4.h>

<md5.h>

<rmd160.h>

<sha1.h>

<sha2.h>

The following headers are provided for compatibility with FreeBSD and DragonFly.

<ripemd.h>

<sha.h>

<sha256.h>

<sha512.h>

## SEE ALSO
md2(3), md4(3), md5(3), rmd160(3), sha1(3), sha2(3).

## HISTORY
The libmd project started in the Debian GNU/kFreeBSD port as part of the libbsd library, as a way to ease porting code from FreeBSD to the GNU-based system. It was subsequently split into a project created on Hadrons.Org (mirrored on FreeDesktop.Org) for other distributions and projects to use, and further extended to match the other BSD interfaces.

It is now distributed as part of most non-BSD distributions


nng

package: libnng-devel

title: nng(7)

summary: nanomsg next generation

text:
# nng(7)

## NAME
nng - nanomsg next generation

## SYNOPSIS
cc ['flags'] 'files' -lnng ['libraries']

## DESCRIPTION
NNG provides a common messaging framework intended to solve common communication problems in distributed applications. It offers a number of protocols, and also a number of transports.

The protocols implement the semantics associated with particular communications scenarios, such as RPC style services, service discovery, publish/subscribe, and so forth.

The transports provide support for underlying transport methods, such as TCP, IPC, websockets, and so forth.

NNG is designed to permit easy creation of new transports and, to a lesser extent, new protocols.

NNG is wire compatible with the SP protocols described in the nanomsg project; projects using libnanomsg <https://github.com/nanomsg/nanomsg> can inter-operate with nng as well as other conforming implementations. (One such implementation is mangos <https://github.com/go-mangos/mangos>.) Applications using NNG which wish to communicate with other libraries must ensure that they only use protocols or transports offered by the other library.

NNG also offers a compatible API, permitting legacy code to be recompiled or relinked against NNG. When doing this, support for certain enhancements or features will likely be absent, requiring the application developer to use the new-style API.

NNG is implemented in pure C; if you need bindings for other languages please check the website <http://nanomsg.org/>.

### Protocols
nng_bus(7)

Bus protocol

nng_pair(7)

Pair protocol

nng_pub(7)

Publisher side of publish/subscribe protocol

nng_pull(7)

Pull side of pipeline protocol

nng_push(7)

Push side of pipeline protocol

nng_sub(7)

Subscriber side of publish/subscribe protocol

nng_rep(7)

Reply side of request/reply protocol

nng_req(7)

Request side of request/reply protocol

nng_respondent(7)

Respondent side of survey protocol

nng_surveyor(7)

Surveyor side of survey protocol

### Transports
nng_inproc(7)

Intra-process transport

nng_ipc(7)

Inter-process transport

nng_socket(7)

BSD socket transport

nng_tls(7)

TLSv1.2 over TCP transport

nng_tcp(7)

TCP (and TCPv6) transport

nng_ws(7)

WebSocket transport

nng_zerotier(7)

ZeroTier transport

### Conceptual Overview
NNG presents a socket view of networking. The sockets are constructed using protocol-specific functions, as a given socket implements precisely one protocol.

Each socket can be used to send and receive messages (if the protocol) supports it, and implements the appropriate protocol semantics. For example, sub sockets automatically filter incoming messages to discard those for topics that have not been subscribed.

NNG sockets are message oriented, so that messages are either delivered wholly, or not at all. Partial delivery is not possible. Furthermore, NNG does not provide any other delivery or ordering guarantees; messages may be dropped or reordered (Some protocols, such as req may offer stronger guarantees by performing their own retry and validation schemes.)

Each socket can have zero, one, or many endpoints, which are either listeners or dialers. (A given socket may freely choose whether it uses listeners, dialers, or both.) These endpoints provide access to underlying transports, such as TCP, etc.

Each endpoint is associated with a URL, which is a service address. For dialers, this will be the service address that will be contacted, whereas for listeners this is where the listener will accept new connections.

Endpoints do not themselves transport data. They are instead responsible for the creation of pipes, which can be thought of as message-oriented connected streams. Pipes frequently correspond to a single underlying byte stream. For example both IPC and TCP transports implement their pipes using a 1:1 relationship with a connected operating system socket.

Endpoints create pipes as needed. Listeners will create them when a new client connection request arrives, and dialers will generally create one, then wait for it to disconnect before reconnecting.

Most applications should not have to worry about endpoints or pipes at all; the socket abstraction should provide all the functionality needed other than in a few specific circumstances.

### Raw Mode
Most applications will use sockets in normal, or cooked, mode. This mode provides the full semantics of the protocol. For example, req sockets will automatically match a reply to a request, and resend requests periodically if no reply was received.

There are situations, such as with proxies, where it is desirable to bypass these semantics and simply pass messages to and from the socket with no extra semantic handling. This is possible using raw mode sockets.

Raw mode sockets are generally constructed with a different function, such as nng_req0_open_raw(). Using these sockets, the application can simply send and receive messages, and is responsible for supplying any additional socket semantics. Typically this means that the application will need to inspect message headers on incoming messages, and supply them on outgoing messages.

Tip The nng_device() function only works with raw mode

sockets, but as it only forwards the messages, no additional application processing is needed.

### URLs
NNG uses universal resource locators (URLs) following the format specified in RFC 3986 <https://tools.ietf.org/html/rfc3986>, including some schemes that are unique to SP.

The URLs used in NNG are canonicalized as follows, mostly in accordance with RFC 3986 6.2.2 <https://tools.ietf.org/html/rfc3986#section-6.2.2>:

1.The URL is parsed into scheme, userinfo, host, port, path, query and fragment components. (Not all of these members are necessarily present.)

2.The scheme, hostname, and port if present, are converted to lower case.

3.Percent-encoded values for unreserved characters <https://tools.ietf.org/html/rfc3986#section-2.3> converted to their unencoded forms.

4.Additionally URL percent-encoded values for characters in the path and with numeric values larger than 127 (i.e. not ASCII) are decoded.

5.The resulting path is checked for invalid UTF-8 sequences, consisting of surrogate pairs, illegal byte sequences, or overlong encodings. If this check fails, then the entire URL is considered invalid.

6.Path segments consisting of . and .. are resolved as per RFC 3986 6.2.2.3 <https://tools.ietf.org/html/rfc3986#section-6.2.2.3>.

7.Further, empty path segments are removed, meaning that duplicate slash (/) separators are removed from the path.

Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing them is believed to improve both the usability and security of applications, without violating RFC 3986 itself.

Tip Port numbers may be service names in some instances, but it is recommended

that numeric port numbers be used when known. If service names are used, it is recommended that they follow the naming conventions for C identifiers, and not be longer than 32 characters in length. This will maximize compatibility across systems and minimize opportunities for confusion when they are parsed on different systems.

### API
The library API is documented at libnng(3).

## SEE ALSO
libnng(3), nng_compat(3compat)


title: nng_bus(7)

summary: bus protocol

text:
# nng_bus(7)

## NAME
nng_bus - bus protocol

## SYNOPSIS

```
#include <nng/protocol/bus0/bus.h>
```

## DESCRIPTION
The bus protocol provides for building mesh networks where every peer is connected to every other peer. In this protocol, each message sent by a node is sent to every one of its directly connected peers.

Tip Messages are only sent to directly connected peers.

This means that in the event that a peer is connected indirectly, it will not receive messages. When using this protocol to build mesh networks, it is therefore important that a fully-connected mesh network be constructed.

All message delivery in this pattern is best-effort, which means that peers may not receive messages. Furthermore, delivery may occur to some, all, or none of the directly connected peers. (Messages are not delivered when peer nodes are unable to receive.) Hence, send operations will never block; instead if the message cannot be delivered for any reason it is discarded.

Tip In order to minimize the likelihood of message loss, this protocol

should not be used for high throughput communications. Furthermore, the more traffic in aggregate that occurs across the topology, the more likely that message loss is to occur.

### Socket Operations
The nng_bus0_open() functions create a bus socket. This socket may be used to send and receive messages. Sending messages will attempt to deliver to each directly connected peer.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The bus protocol has no protocol-specific options.

### Protocol Headers
When using a bus socket in raw mode, received messages will contain the incoming pipe ID as the sole element in the header. If a message containing such a header is sent using a raw bus socket, then, the message will be delivered to all connected pipes except the one identified in the header. This behavior is intended for use with device configurations consisting of just a single socket. Such configurations are useful in the creation of rebroadcasters, and this capability prevents a message from being routed back to its source. If no header is present, then a message is sent to all connected pipes.

When using normal (cooked mode) bus sockets, no message headers are present.

## SEE ALSO
nng_bus_open(3), nng(7)


title: nng_inproc(7)

summary: intra\-process transport

text:
# nng_inproc(7)

## NAME
nng_inproc - intra-process transport

## SYNOPSIS

```
#include <nng/transport/inproc/inproc.h>
int nng_inproc_register(void);
```

## DESCRIPTION

The inproc transport provides communication support between sockets within the same process. This may be used as an alternative to slower transports when data must be moved within the same process.

This transport tries hard to avoid copying data, and thus is very light-weight.

### Registration
This transport is generally built-in to the core, so no extra steps to use it should be necessary.

### URI Format
This transport uses URIs using the scheme inproc://, followed by an arbitrary string of text, terminated by a NUL byte.

Multiple URIs can be used within the same application, and they will not interfere with one another.

Two applications may also use the same URI without interfering with each other, and they will be unable to communicate with each other using that URI.

### Socket Address
When using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_inproc.

### Transport Options
The inproc transport has no special options.

Note While inproc accepts the option

NNG_OPT_RECVMAXSZ for compatibility, the value of the option is ignored with no enforcement. As inproc peers are in the same address space, they are implicitly trusted, and thus it makes no sense to spend cycles protecting a program from itself.

## SEE ALSO
nng_inproc_register(3), nng_sockaddr_inproc(5), nng(7)


title: nng_ipc(7)

summary: IPC transport

text:
# nng_ipc(7)

## NAME
nng_ipc - IPC transport

## SYNOPSIS

```
#include <nng/transport/ipc/ipc.h>
int nng_ipc_register(void);
```

## DESCRIPTION
The ipc transport provides communication support between sockets within different processes on the same host. For POSIX platforms, this is implemented using UNIX domain sockets. For Windows, this is implemented using Windows Named Pipes. Other platforms may have different implementation strategies.

### Registration
This transport is generally built-in to the core, so no extra steps to use it should be necessary.

### Traditional Names
This transport uses URIs using the scheme ipc://, followed by a path name in the file system where the socket or named pipe should be created.

Tip On Windows, all names are prefixed by \\.\pipe\ and do not

reside in the normal file system. On POSIX platforms, the path is taken literally, and is relative to the current directory, unless it begins with /, in which case it is relative to the root directory.

Note When using relative paths on POSIX systems, the address used and returned

in properties like NNG_OPT_LOCADDR and NNG_OPT_URL will also be relative. Consequently, they will only be interpreted the same by processes that have the same working directory. To ensure maximum portability and safety, absolute paths are recommended whenever possible.

Note If compatibility with legacy nanomsg applications is required,

then path names must not be longer than 122 bytes, including the final NUL byte. This is because legacy versions of nanomsg cannot express URLs longer than 128 bytes, including the ipc:// prefix.

### UNIX Aliases
The unix:// scheme is an alias for ipc:// and can be used inter-changeably, but only on POSIX systems.

The purpose of this scheme is to support a future transport making use of AF_UNIX on Windows systems, at which time it will be necessary to discriminate between the Named Pipes and the AF_UNIX based transports.

### Abstract Names
On Linux, this transport also can support abstract sockets. Abstract sockets use a URI-encoded name after the scheme, which allows arbitrary values to be conveyed in the path, including embedded NUL bytes. For example, the name "a\0b" would be represented as abstract://a%00b.

Tip An empty name may be used with a listener to request “auto bind” be used to select a name.

In this case the system will allocate a free name. The name assigned may be retrieved using NNG_OPT_LOCADDR.

Note NNG cannot represent an abstract socket with the empty name.

Note Abstract names do not include the leading NUL byte used in the low-level socket address.

Abstract sockets do not have any representation in the file system, and are automatically freed by the system when no longer in use. Abstract sockets ignore socket permissions, but it is still possible to determine the credentials of the peer with NNG_OPT_PEER_UID, etc.

### Socket Address
When using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_ipc, except for abstract sockets, which use nng_sockaddr_abstract.

### Transport Options
The following transport options are supported by this transport, where supported by the underlying platform.

•NNG_OPT_IPC_PERMISSIONS

•NNG_OPT_IPC_SECURITY_DESCRIPTOR

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

•NNG_OPT_PEER_GID

•NNG_OPT_PEER_PID

•NNG_OPT_PEER_UID

•NNG_OPT_PEER_ZONEID

•NNG_OPT_URL

## SEE ALSO
nng_sockaddr(5), nng_ipc_options(5), nng_options(5), nng(7)


title: nng_pair(7)

summary: pair protocol

text:
# nng_pair(7)

## NAME
nng_pair - pair protocol

## SYNOPSIS
Version 0

```
#include <nng/protocol/pair0/pair.h>
```

Version 1

```
#include <nng/protocol/pair1/pair.h>
```

## DESCRIPTION
The pair protocol implements a peer-to-peer pattern, where relationships between peers are one-to-one.

### Socket Operations
The nng_pair_open() functions create a pair socket.

Normally, this pattern will block when attempting to send a message if no peer is able to receive the message.

Note Even though this mode may appear to be reliable, because back-pressure

prevents discarding messages most of the time, there are topologies involving devices (see nng_device()) or raw mode sockets (see NNG_OPT_RAW) where messages may be discarded. Applications that require reliable delivery semantics should consider using req sockets, or implement their own acknowledgment layer on top of pair sockets.

### Protocol Versions
Version 0 is the legacy version of this protocol. It lacks any header information, and is suitable when building simple one-to-one topologies.

Tip Use version 0 if you need to communicate with other implementations,

including the legacy nanomsg <https://github.com/nanomsg/nanomsg> library or mangos <https://github.com/go-mangos/mangos>.

Version 1 of the protocol offers improved protection against loops when used with nng_device().

### Polyamorous Mode

Warning Polyamorous mode is deprecated, and support for it will likely

be removed in a future release. Applications are strongly discouraged from making further use of it.

Normally pair sockets are for one-to-one communication, and a given peer will reject new connections if it already has an active connection to another peer.

Polyamorous mode changes this, to allow a socket to communicate with multiple directly-connected peers. This mode is enabled by opening a socket with the nng_pair1_open_poly() function

Note Polyamorous mode is only available when using pair version 1.

In polyamorous mode a socket can support many one-to-one connections. In this mode, the application must choose the remote peer to receive an outgoing message by setting the nng_pipe to use for the outgoing message with the nng_msg_set_pipe() function.

If no remote peer is specified by the sender, then the protocol will select any available connected peer.

Most often the value of the outgoing pipe will be obtained from an incoming message using the nng_msg_get_pipe() function, such as when replying to an incoming message.

Note Directed send only works with directly connected peers.

It will not function across device proxies.

In order to prevent head-of-line blocking, if the peer on the given pipe is not able to receive (or the pipe is no longer available, such as if the peer has disconnected), then the message will be discarded with no notification to the sender.

### Protocol Options
The following protocol-specific options are available.

NNG_OPT_MAXTTL

(int, version 1 only). Maximum time-to-live.

NNG_OPT_PAIR1_POLY

(bool, version 1 only) This option is no longer supported. Formerly it was used to configure polyamorous mode, but that mode is now established by using the nng_pair1_open_poly() function.

### Protocol Headers
Version 0 of the pair protocol has no protocol-specific headers.

Version 1 of the pair protocol uses a single 32-bit unsigned value. The low-order (big-endian) byte of this value contains a "hop" count, and is used in conjunction with the NNG_OPT_MAXTTL option to guard against device forwarding loops. This value is initialized to 1, and incremented each time the message is received by a new node.

## SEE ALSO
nng_pair_open(3), nng_options(5), nng(7)


title: nng_pub(7)

summary: publisher protocol

text:
# nng_pub(7)

## NAME
nng_pub - publisher protocol

## SYNOPSIS

```
#include <nng/protocol/pubsub0/pub.h>
```

## DESCRIPTION
The pub protocol is one half of a publisher/subscriber pattern. In this pattern, a publisher sends data, which is broadcast to all subscribers. The subscribing applications only see the data to which they have subscribed.

The pub protocol is the publisher side, and the sub protocol is the subscriber side.

Note In this implementation, the publisher delivers all messages to all

subscribers. The subscribers maintain their own subscriptions, and filter them locally. Thus, this pattern should not be used in an attempt to reduce bandwidth consumption.

The topics that subscribers subscribe to is just the first part of the message body. Applications should construct their messages accordingly.

### Socket Operations
The nng_pub0_open() functions create a publisher socket. This socket may be used to send messages, but is unable to receive them. Attempts to receive messages will result in NNG_ENOTSUP.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The pub protocol has no protocol-specific options.

### Protocol Headers
The pub protocol has no protocol-specific headers.

## SEE ALSO
nng_pub_open(3), nng_sub(7), nng(7)


title: nng_pull(7)

summary: pull protocol

text:
# nng_pull(7)

## NAME
nng_pull - pull protocol

## SYNOPSIS

```
#include <nng/protocol/pipeline0/pull.h>
```

## DESCRIPTION
The pull protocol is one half of a pipeline pattern. The other half is the push protocol.

In the pipeline pattern, pushers distribute messages to pullers. Each message sent by a pusher will be sent to one of its peer pullers, chosen in a round-robin fashion from the set of connected peers available for receiving. This property makes this pattern useful in load-balancing scenarios.

### Socket Operations
The nng_pull0_open() functions create a puller socket. This socket may be used to receive messages, but is unable to send them. Attempts to send messages will result in NNG_ENOTSUP.

When receiving messages, the pull protocol accepts messages as they arrive from peers. If two peers both have a message ready, the order in which messages are handled is undefined.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The pull protocol has no protocol-specific options.

### Protocol Headers
The pull protocol has no protocol-specific headers.

## SEE ALSO
nng_pull_open(3), nng_push(7), nng(7),


title: nng_push(7)

summary: push protocol

text:
# nng_push(7)

## NAME
nng_push - push protocol

## SYNOPSIS

```
#include <nng/protocol/pipeline0/push.h>
```

## DESCRIPTION
The push protocol is one half of a pipeline pattern. The other side is the pull protocol.

In the pipeline pattern, pushers distribute messages to pullers. Each message sent by a pusher will be sent to one of its peer pullers, chosen in a round-robin fashion from the set of connected peers available for receiving. This property makes this pattern useful in load-balancing scenarios.

### Socket Operations
The nng_push0_open() call creates a pusher socket. This socket may be used to send messages, but is unable to receive them. Attempts to receive messages will result in NNG_ENOTSUP.

Send operations will observe flow control (back-pressure), so that only peers capable of accepting a message will be considered. If no peer is available to receive a message, then the send operation will wait until one is available, or the operation times out.

Note Although the pipeline protocol honors flow control, and attempts

to avoid dropping messages, no guarantee of delivery is made. Furthermore, as there is no capability for message acknowledgment, applications that need reliable delivery are encouraged to consider the req protocol instead.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
NNG_OPT_SENDBUF

(int, 0 - 8192) Normally this is set to zero, indicating that send operations are unbuffered. In unbuffered operation, send operations will wait until a suitable peer is available to receive the message. If this is set to a positive value (up to 8192), then an intermediate buffer is provided for the socket with the specified depth (in messages).

Note Transport layer buffering may occur in addition to any socket

buffer determined by this option.

### Protocol Headers
The push protocol has no protocol-specific headers.

## SEE ALSO
nng_push(3), nng_pull(7), nng_req(7), nng(7)


title: nng_rep(7)

summary: reply protocol

text:
# nng_rep(7)

## NAME
nng_rep - reply protocol

## SYNOPSIS

```
#include <nng/protocol/reqrep0/rep.h>
```

## DESCRIPTION
The rep protocol is one half of a request/reply pattern. In this pattern, a requester sends a message to one replier, who is expected to reply. The request is resent if no reply arrives, until a reply is received or the request times out.

Tip This protocol is useful in setting up RPC-like services.

It is also reliable, in that a requester will keep retrying until a reply is received.

The rep protocol is the replier side, and the req protocol is the requester side.

### Socket Operations
The nng_rep0_open() functions create a replier socket. This socket may be used to receive messages (requests), and then to send replies.

Generally a reply can only be sent after receiving a request.

Send operations will result in NNG_ESTATE if no corresponding request was previously received.

Likewise, only one receive operation may be pending at a time. Any additional concurrent receive operations will result in NNG_ESTATE.

Raw mode sockets ignore all these restrictions.

### Context Operations
This protocol supports the creation of contexts for concurrent use cases using nng_ctx_open().

Each context may have at most one outstanding request, and operates independently of the others. The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The rep protocol has no protocol-specific options.

### Protocol Headers
The rep protocol uses a backtrace in the header. This is more fully documented in the req manual.

## SEE ALSO
nng_rep_open(3), nng(7), nng_req(7)


title: nng_req(7)

summary: request protocol

text:
# nng_req(7)

## NAME
nng_req - request protocol

## SYNOPSIS

```
#include <nng/protocol/reqrep0/req.h>
```

## DESCRIPTION
The req protocol is one half of a request/reply pattern. In this pattern, a requester sends a message to one replier, who is expected to reply. The request is resent if no reply arrives, until a reply is received or the request times out.

Tip This protocol is useful in setting up RPC-like services.

It is also "reliable", in that a the requester will keep retrying until a reply is received.

Note Because requests are resent, it is important that they be idempotent

to ensure predictable and repeatable behavior even in the face of duplicated requests, which can occur (for example if a reply message is lost for some reason.)

The requester generally only has one outstanding request at a time unless in raw mode (via NNG_OPT_RAW), and it will generally attempt to spread work requests to different peer repliers.

Tip This property, when combined with nng_device()

can help provide a degree of load-balancing.

The req protocol is the requester side, and the rep protocol is the replier side.

### Socket Operations
The nng_req0_open() functions create a requester socket. This socket may be used to send messages (requests), and then to receive replies.

Generally a reply can only be received after sending a request. (Attempts to receive a message will result in NNG_ESTATE if there is no outstanding request.)

Furthermore, only a single receive operation may be pending at a time. Attempts to post more receive operations concurrently will result in NNG_ESTATE.

Requests may be canceled by sending a different request. This will cause the requester to discard any reply from the earlier request, but it will not stop a replier from processing a request it has already received or terminate a request that has already been placed on the wire.

Raw mode sockets ignore all these restrictions.

### Context Operations
This protocol supports the creation of contexts for concurrent use cases using nng_ctx_open().

The NNG_OPT_REQ_RESENDTIME value may be configured differently on contexts created this way.

Each context may have at most one outstanding request, and operates independently from the others.

The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The following protocol-specific option is available.

NNG_OPT_REQ_RESENDTIME

(nng_duration) When a new request is started, a timer of this duration is also started. If no reply is received before this timer expires, then the request will be resent. (Requests are also automatically resent if the peer to whom the original request was sent disconnects, or if a peer becomes available while the requester is waiting for an available peer.)

Resending may be deferred up to the value of the NNG_OPT_RESENDTICK parameter.

NNG_OPT_REQ_RESENDTICK

(nng_duration) This is the granularity of the clock that is used to check for resending. The default is a second. Setting this to a higher rate will allow for more timely resending to occur, but may incur significant additional overhead when the socket has many outstanding requests (contexts). When there are no requests outstanding that have a resend set, then the clock does not tick at all.

This option is shared for all contexts on a socket, and is only available for the socket itself.

### Protocol Headers
This protocol uses a backtrace in the header. This form uses a stack of 32-bit big-endian identifiers. There must be at least one identifier, the request ID, which will be the last element in the array, and must have the most significant bit set.

There may be additional peer IDs preceding the request ID. These will be distinguishable from the request ID by having their most significant bit clear.

When a request message is received by a forwarding node (see nng_device()), the forwarding node prepends a 32-bit peer ID (which must have the most significant bit clear), which is the forwarder’s way of identifying the directly connected peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.)

It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination for the reply.)

When a reply message is created, it is created using the same headers that the request contained.

A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so.

When the reply finally arrives back at the initiating requester, it should have only a single element in the message, which will be the request ID it originally used for the request.

## SEE ALSO
nng_ctx_open(3), nng_device(3), nng_req_open(3), nng_ctx(5), nng(7), nng_rep(7)


title: nng_respondent(7)

summary: respondent protocol

text:
# nng_respondent(7)

## NAME
nng_respondent - respondent protocol

## SYNOPSIS

```
#include <nng/protocol/survey0/respond.h>
```

## DESCRIPTION
The respondent protocol is one half of a survey pattern. In this pattern, a surveyor sends a survey, which is broadcast to all peer respondents. The respondents then have a chance to reply (but are not obliged to reply). The survey itself is a timed event, so that responses received after the survey has finished are discarded.

Tip This protocol is useful in solving voting problems, such as leader

election in cluster configurations, as well as certain kinds of service discovery problems.

The respondent protocol is the respondent side, and the surveyor protocol is the surveyor side.

### Socket Operations
The nng_respondent0_open() functions create a respondent socket. This socket may be used to receive messages, and then to send replies. A reply can only be sent after receiving a survey, and generally the reply will be sent to surveyor from whom the last survey was received.

Respondents may discard a survey by simply not replying to it.

Raw mode sockets (set with NNG_OPT_RAW) ignore all these restrictions.

### Context Operations
This protocol supports the creation of contexts for concurrent use cases using nng_ctx_open().

Incoming surveys will be routed to and received by only one context. Additional surveys may be received by other contexts in parallel. Replies made using a context will be returned to the the surveyor that issued the survey most recently received by that context. The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined. An earlier and incompatible version of the protocol was used in older pre-releases of nanomsg <http://nanomsg.org>, but was not released in any production version.)

### Protocol Options
The respondent protocol has no protocol-specific options.

### Protocol Headers
The respondent protocol uses a backtrace in the header. This is more fully documented in the surveyor manual.

## SEE ALSO
nng_respondent_open(3), nng_surveyor(7), nng(7)


title: nng_socket(7)

summary: BSD Socket transport (experimental)

text:
# nng_socket(7)

## NAME
nng_socket - BSD Socket transport (experimental)

## DESCRIPTION
The socket transport supports communication between peers across arbitrary BSD sockets, such as those that are created with nng_socket_pair().

This transport only supports listeners, using nng_listener_create().

Note Attempts to create dialers using this transport will result in NNG_ENOTSUP.

The socket file descriptor is passed to the listener using the NNG_OPT_SOCKET_FD option (as an integer). Setting this option will cause the listener to create a pipe associated backed by the file descriptor.

The protocol between peers using this transport is compatible with the protocol used for the TCP transport, but this is an implementation detail and subject to change without notice.

Note This transport is experimental, and at present is only supported on POSIX platforms.

### Registration
No special action is necessary to register this transport.

### URI Format
This transport uses the URL socket://, without further qualification.

### Socket Address
The socket address will be of family NNG_AF_UNSPEC. There are no further socket details available.

### Transport Options
The following transport option is available:

NNG_OPT_SOCKET_FD

(int) This is a write-only option, that may be set multiple times on a listener. Each time this is set, the listener will create a pipe backed by the given file descriptor passed as an argument.

Additionally, the following options may be supported on pipes when the platform supports them:

•NNG_OPT_PEER_GID

•NNG_OPT_PEER_PID

•NNG_OPT_PEER_UID

•NNG_OPT_PEER_ZONEID

## SEE ALSO
nng_socket_pair(3), nng_dialer(5), nng_listener(5), nng_options(5), nng_pipe(5), nng_sockaddr(5), nng(7)


title: nng_sub(7)

summary: subscriber protocol

text:
# nng_sub(7)

## NAME
nng_sub - subscriber protocol

## SYNOPSIS

```
#include <nng/nng.h>
#include <nng/protocol/pubsub0/sub.h>
```

## DESCRIPTION
The sub protocol is one half of a publisher/subscriber pattern. In this pattern, a publisher sends data, which is broadcast to all subscribers. The subscribing applications only see the data to which they have subscribed.

The sub protocol is the subscriber side, and the pub protocol is the publisher side.

Note In this implementation, the publisher delivers all messages to all

subscribers. The subscribers maintain their own subscriptions, and filter them locally. Thus, this pattern should not be used in an attempt to reduce bandwidth consumption.

The topics that subscribers subscribe to is just the first part of the message body. Applications should construct their messages accordingly.

### Socket Operations
The nng_sub0_open() functions create a subscriber socket. This socket may be used to receive messages, but is unable to send them. Attempts to send messages will result in NNG_ENOTSUP.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

### Protocol Options
The following protocol-specific options are available.

NNG_OPT_SUB_SUBSCRIBE

This option registers a topic that the subscriber is interested in. The option is write-only, and takes an array of bytes, of arbitrary size. Each incoming message is checked against the list of subscribed topics. If the body begins with the entire set of bytes in the topic, then the message is accepted. If no topic matches, then the message is discarded.

Note This option is deprecated. New applications should use

nng_sub0_socket_subscribe or nng_sub0_ctx_subscribe functions.

Note This option is a byte array. Thus if you use

nng_setopt_string() the NUL terminator byte will be included in the topic. If that isn’t desired, consider using nng_setopt() and using strlen() of the topic as the topic size.

Tip To receive all messages, an empty topic (zero length) can be used.

NNG_OPT_SUB_UNSUBSCRIBE

This option, also write-only, removes a topic from the subscription list. Note that if the topic was not previously subscribed to with NNG_OPT_SUB_SUBSCRIBE then an NNG_ENOENT error will result. + NOTE: This option is deprecated. New applications should use nng_sub0_socket_unsubscribe or nng_sub0_ctx_unsubscribe functions.

NNG_OPT_SUB_PREFNEW

(bool) This read/write option specifies the behavior of the subscriber when the queue is full. When true (the default), the subscriber will make room in the queue by removing the oldest message. When false, the subscriber will reject messages if the message queue does not have room.

### Protocol Headers
The sub protocol has no protocol-specific headers.

## SEE ALSO
nng_sub_open(3), nng_sub_subscribe(3), nng_pub(7), nng(7)


title: nng_surveyor(7)

summary: surveyor protocol

text:
# nng_surveyor(7)

## NAME
nng_surveyor - surveyor protocol

## SYNOPSIS

```
#include <nng/nng.h>
#include <nng/protocol/survey0/survey.h>
```

## DESCRIPTION
The surveyor protocol is one half of a survey pattern. In this pattern, a surveyor sends a survey, which is broadcast to all peer respondents. The respondents then have a chance to reply (but are not obliged to reply). The survey itself is a timed event, so that responses received after the survey has finished are discarded.

Tip This protocol is useful in solving voting problems, such as

leader election in cluster configurations, as well as certain kinds of service discovery problems.

The surveyor protocol is the surveyor side, and the respondent protocol is the respondent side.

### Socket Operations
The nng_surveyor0_open() functions create a surveyor socket. This socket may be used to send messages (surveys), and then to receive replies. A reply can only be received after sending a survey. A surveyor can normally expect to receive at most one reply from each responder. (Messages can be duplicated in some topologies, so there is no guarantee of this.)

Attempts to receive on a socket with no outstanding survey will result in NNG_ESTATE. If the survey times out while the surveyor is waiting for replies, then the result will be NNG_ETIMEDOUT.

Only one survey can be outstanding at a time; sending another survey will cancel the prior one, and any responses from respondents from the prior survey that arrive after this will be discarded.

Raw mode sockets ignore all these restrictions.

### Context Operations
This protocol supports the creation of contexts for concurrent use cases using nng_ctx_open().

Each context can initiate its own surveys, and it will receive only responses to its own outstanding surveys. Other contexts on the same socket may have overlapping surveys operating at the same time.

Each of these may have their own timeouts established with NNG_OPT_SURVEYOR_SURVEYTIME.

Additionally, sending a survey on a context will only cancel an outstanding survey on the same context.

Note Due to the best-effort nature of this protocol, if too may contexts

are attempting to perform surveys simultaneously, it is possible for either individual outgoing surveys or incoming responses to be lost.

### Protocol Versions
Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined. An earlier and incompatible version of the protocol was used in older pre-releases of nanomsg <http://nanomsg.org>, but was not released in any production version.)

### Protocol Options
The following protocol-specific options is available.

NNG_OPT_SURVEYOR_SURVEYTIME

(nng_duration) Duration of surveys. When a new survey is started, a timer of this duration is also started. Any responses arriving this time will be discarded. Attempts to receive after the timer expires with no other surveys started will result in NNG_ESTATE. Attempts to receive when this timer expires will result in NNG_ETIMEDOUT.

### Protocol Headers
This form uses a stack of 32-bit big-endian identifiers. There must be at least one identifier, the survey ID, which will be the last element in the array, and must have the most significant bit set.

There may be additional peer IDs preceding the survey ID. These will be distinguishable from the survey ID by having their most significant bit clear.

When a survey message is received by a forwarding node (see nng_device()), the forwarding node prepends a 32-bit peer ID (which must have the most significant bit clear), which is the forwarder’s way of identifying the directly connected peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.)

It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination for the response.)

When a response message is created, it is created using the same headers that the survey contained.

A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so.

When the response finally arrives back at the initiating surveyor, it should have only a single element in the message, which will be the survey ID it originally used for the request.

More detail can be found in the RFC sp-surveyor-01 <https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt> document.

## SEE ALSO
nng_surveyor_open(3), nng_respondent(7), nng(7)


title: nng_tcp(7)

summary: TCP/IP transport

text:
# nng_tcp(7)

## NAME
nng_tcp - TCP/IP transport

## SYNOPSIS

```
#include <nng/transport/tcp/tcp.h>
int nng_tcp_register(void);
```

## DESCRIPTION
The tcp transport provides communication support between sockets across a TCP/IP network. Both IPv4 and IPv6 are supported when the underlying platform also supports it.

### Registration
This transport is generally built-in to the core of NNG, so no extra steps to use it should be necessary.

### URI Format
This transport uses URIs using the scheme tcp://, followed by an IP address or hostname, followed by a colon and finally a TCP port number. For example, to contact port 80 on the localhost either of the following URIs could be used: tcp://127.0.0.1:80 or tcp://localhost:80.

A URI may be restricted to IPv6 using the scheme tcp6://, and may be restricted to IPv4 using the scheme tcp4://.

Note Specifying tcp6:// may not prevent IPv4 hosts from being used with

IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with listeners. The details of this varies across operating systems.

Note Both tcp6:// and tcp4:// are specific to NNG, and might not

be understood by other implementations.

Tip We recommend using either numeric IP addresses, or names that are

specific to either IPv4 or IPv6 to prevent confusion and surprises.

When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

For example, the same port 80 on the IPv6 loopback address (::1) would be specified as tcp://[::1]:80.

The special value of 0 (INADDR_ANY) can be used for a listener to indicate that it should listen on all interfaces on the host. A short-hand for this form is to either omit the address, or specify the asterisk (*) character. For example, the following three URIs are all equivalent, and could be used to listen to port 9999 on the host:

1.tcp://0.0.0.0:9999

2.tcp://*:9999

3.tcp://:9999

The entire URI must be less than NNG_MAXADDRLEN bytes long.

### Socket Address
When using an nng_sockaddr structure, the actual structure is either of type nng_sockaddr_in (for IPv4) or nng_sockaddr_in6 (for IPv6).

### Transport Options
The following transport options are supported by this transport, where supported by the underlying platform.

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

•NNG_OPT_TCP_KEEPALIVE

•NNG_OPT_TCP_NODELAY

•NNG_OPT_URL

## SEE ALSO
nng_options(5), nng_sockaddr(5), nng_sockaddr_in(5), nng_sockaddr_in6(5), nng_tcp_options(5), nng(7)


title: nng_tls(7)

summary: TLS transport

text:
# nng_tls(7)

## NAME
nng_tls - TLS transport

## SYNOPSIS

```
#include <nng/transport/tls/tls.h>
int nng_tls_register(void);
```

## DESCRIPTION
The tls transport provides communication support between peers across a TCP/IP network using TLS v1.2 <https://tools.ietf.org/html/rfc5246> on top of TCP <https://tools.ietf.org/html/rfc793>. Both IPv4 and IPv6 are supported when the underlying platform also supports it.

The protocol details are documented in TLS Mapping for Scalability Protocols <http://nanomsg.org/rfcs/sp-tls-v1.html>.

### Registration
Depending upon how the library was built, it may be necessary to register the transport by calling nng_tls_register().

### Availability
The tls transport depends on the use of an external library. As of this writing, mbedTLS <https://tls.mbed.org/> version 2.0 or later is required.

Tip Applications may need to add this library (or libraries) to

their link line, particularly when using a statically built library.

Note The mbedTLS library uses different licensing terms than

NNG itself; as of this writing it is offered under either Apache License 2.0 <https://opensource.org/licenses/Apache-2.0> or GNU GPL <https://opensource.org/licenses/gpl-license> terms. You are responsible for understanding and adhering to the license terms of any libraries you use.

### URI Format
This transport uses URIs using the scheme tls+tcp://, followed by an IP address or hostname, followed by a colon and finally a TCP port number. For example, to contact port 4433 on the localhost either of the following URIs could be used: tls+tcp://127.0.0.1:4433 or tls+tcp://localhost:4433.

A URI may be restricted to IPv6 using the scheme tls+tcp6://, and may be restricted to IPv4 using the scheme tls+tcp4://.

Note Specifying tls+tcp6:// may not prevent IPv4 hosts from being used with

IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with listeners. The details of this varies across operating systems.

Note Both tls+tcp6:// and tls+tcp4:// are specific to NNG, and may not

be understood by other implementations.

Tip We recommend using either numeric IP addresses, or names that are

specific to either IPv4 or IPv6 to prevent confusion and surprises.

When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

For example, the same port 4433 on the IPv6 loopback address ('::1') would be specified as tls+tcp://[::1]:4433.

Tip Certificate validation generally works when using names

rather than IP addresses. This transport automatically uses the name supplied in the URL when validating the certificate supplied by the server.

The special value of 0 (INADDR_ANY) can be used for a listener to indicate that it should listen on all interfaces on the host. A short-hand for this form is to either omit the address, or specify the asterisk (*) character. For example, the following three URIs are all equivalent, and could be used to listen to port 9999 on the host:

1.tls+tcp://0.0.0.0:9999

2.tls+tcp://*:9999

3.tls+tcp://:9999

The entire URI must be less than NNG_MAXADDRLEN bytes long.

### Socket Address
When using an nng_sockaddr structure, the actual structure is either of type nng_sockaddr_in (for IPv4) or nng_sockaddr_in6 (for IPv6).

### Transport Options
The following transport options are available. Note that setting these must be done before the transport is started.

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

•NNG_OPT_TCP_KEEPALIVE

•NNG_OPT_TCP_NODELAY

•NNG_OPT_TLS_AUTH_MODE

•NNG_OPT_TLS_CA_FILE

•NNG_OPT_TLS_CERT_KEY_FILE

•NNG_OPT_TLS_CONFIG

•NNG_OPT_TLS_VERIFIED_

•NNG_OPT_TLS_PEER_CN

•NNG_OPT_TLS_PEER_ALT_NAMES

•NNG_OPT_URL

## SEE ALSO
nng_tls_config_alloc(3tls) nng_options(5), nng_sockaddr_in(5), nng_sockaddr_in6(5), nng_tcp_options(5), nng_tls_config(5), nng_tls_options(5), nng(7),


title: nng_ws(7)

summary: WebSocket transport

text:
# nng_ws(7)

## NAME
nng_ws - WebSocket transport

## SYNOPSIS

```
#include <nng/transport/websocket/ws.h>
int nng_ws_register(void);
int nng_wss_register(void);
```

## DESCRIPTION
The ws transport provides communication support between peers across a TCP/IP network using WebSockets <https://tools.ietf.org/html/rfc6455>. Both IPv4 and IPv6 are supported when the underlying platform also supports it.

The protocol details are documented in WebSocket Mapping for Scalability Protocols <http://nanomsg.org/rfcs/sp-websocket-v1.html>.

### Registration
Depending upon how the library was built, it may be necessary to register the transport by calling nng_ws_register().

If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) can be used as well, but the secure transport may have to be registered using the nng_wss_register() function.

### URI Format
This transport uses URIs using the scheme ws://, followed by an IP address or hostname, optionally followed by a colon and an TCP port number, optionally followed by a path. (If no port number is specified then port 80 is assumed. If no path is specified then a path of / is assumed.) For example, the URI ws://localhost/app/pubsub would use port 80 on localhost, with the path /app/pubsub.

Secure WebSockets (if enabled) use the scheme wss://, and the default TCP port number of 443. Otherwise the format is the same as for regular WebSockets.

A URI may be restricted to IPv6 using the scheme ws6:// or wss6://, and may be restricted to IPv4 using the scheme ws4:// or wss4://.

Note Specifying ws6:// or wss6:// may not prevent IPv4 hosts from being used with

IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with listeners. The details of this varies across operating systems.

Note The ws4:// , ws6://, wss4:// and wss6:// schemes are specific to NNG,

and might not be understood by other implementations.

Tip We recommend using either numeric IP addresses, or names that are

specific to either IPv4 or IPv6 to prevent confusion and surprises.

When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

For example, the same path and port on the IPv6 loopback address (::1) would be specified as ws://[::1]/app/pubsub.

Note The value specified as the host, if any, will also be used

in the Host: HTTP header during HTTP negotiation.

To listen to all ports on the system, the host name may be elided from the URL on the listener. This will wind up listening to all interfaces on the system, with possible caveats for IPv4 and IPv6 depending on what the underlying system supports. (On most modern systems it will map to the special IPv6 address ::, and both IPv4 and IPv6 connections will be permitted, with IPv4 addresses mapped to IPv6 addresses.)

### Socket Address
When using an nng_sockaddr structure, the actual structure is either of type nng_sockaddr_in (for IPv4) or nng_sockaddr_in6 (for IPv6).

### Server Instances
This transport makes use of shared HTTP server instances, permitting multiple sockets or listeners to be configured with the same hostname and port. When creating a new listener, it is registered with an existing HTTP server instance if one can be found. Note that the matching algorithm is somewhat simple, using only a string based hostname or IP address and port to match. Therefore it is recommended to use only IP addresses or the empty string as the hostname in listener URLs.

Likewise, when sharing a server instance, it may not be possible to alter TLS configuration if the server is already running, as there is only a single TLS configuration context for the entire server instance.

All sharing of server instances is only typically possible within the same process.

The server may also be used by other things (for example to serve static content), in the same process.

### Transport Options
The following transport options are available. Note that setting these must be done before the transport is started.

Note The TLS specific options (beginning with NNG_OPT_TLS_) are

only available for wss:// endpoints.

NNG_OPT_WS_REQUEST_HEADERS

(string) Concatenation of multiple lines terminated by CRLF sequences, that can be used to add further headers to the HTTP request sent when connecting. This option can be set on dialers, and retrieved from pipes.

NNG_OPT_WS_RESPONSE_HEADERS

(string) Concatenation of multiple lines terminated by CRLF sequences, that can be used to add further headers to the HTTP response sent when connecting. This option can be set on listeners, and retrieved from pipes.

NNG_OPT_WS_RECV_TEXT

(bool) Enable receiving of TEXT frames at the WebSocket layer. This option should only be used with the low level nng_stream API. When set, the stream will accept in-bound TEXT frames as well as BINARY frames.

Note The SP protocols (such as REQ) require BINARY frames as they pass binary protocol data.

Hence this option should not be used with such protocols.

Note RFC 6455 requires that TEXT frames be discarded and the connection closed if the frame does not contain valid UTF-8 data.

NNG does not perform any such validation. Applications that need to be strictly conformant should check for this themselves.

NNG_OPT_WS_SEND_TEXT

(bool) Enable sending of TEXT frames at the WebSocket layer. This option should only be used with the low level nng_stream API. When set, the stream will send TEXT frames instead of BINARY frames.

Note NNG does not check the frame data, and will attempt to send whatever the client requests.

Peers that are compliant with RFC 6455 will discard TEXT frames (and break the connection) if they do not contain valid UTF-8.

NNG_OPT_TLS_CONFIG

(nng_tls_config *) The underlying TLS configuration object for wss:// endpoints. A hold is placed on the underlying configuration object before returning it. The caller should release the object with nng_tls_config_free() when it no longer needs the TLS configuration.

Tip Use this option when advanced TLS configuration is required.

NNG_OPT_TLS_CA_FILE

(string) Write-only option naming a file containing certificates to use for peer validation. See nng_tls_config_ca_file() for more information.

NNG_OPT_TLS_CERT_KEY_FILE

(string) Write-only option naming a file containing the local certificate and associated private key. The private key used must be unencrypted. See nng_tls_config_own_cert() for more information.

NNG_OPT_TLS_AUTH_MODE

(int) Write-only option used to configure the authentication mode used. See nng_tls_config_auth_mode() for more details.

NNG_OPT_TLS_VERIFIED

(bool) Whether the remote peer has been properly verified using TLS authentication. May return incorrect results if peer authentication is disabled.

NNG_OPT_TLS_PEER_CN

(string) This read-only option returns the common name of the peer certificate. May return incorrect results if peer authentication is disabled.

NNG_OPT_TLS_PEER_ALT_NAMES

(string list) returns string list with the subject alternative names of the peer certificate. May return incorrect results if peer authentication is disabled.

## SEE ALSO
nng_tls_config_alloc(3tls), nng_sockaddr(5), nng_sockaddr_in(5), nng_sockaddr_in6(5), nng(7)


title: nng_zerotier(7)

summary: ZeroTier transport

text:
# nng_zerotier(7)

## NAME
nng_zerotier - ZeroTier transport

## SYNOPSIS

```
#include <nng/transport/zerotier/zerotier.h>
int nng_zt_register(void);
```

## DESCRIPTION
The zt transport provides communication support for NNG applications over a ZeroTier <http://www.zerotier.com> network, using a Virtual Layer 2 packet facility.

Important This transport is experimental.

To utilize it at present, the library must be built with support, and linked against a suitable libzerotiercore library. Further information about building with this support are in the build documentation included with the distribution.

Important The libzerotiercore library at present is covered under different

license terms than the rest of NNG. Please be careful to review and adhere to the licensing terms.

Important The ZeroTier transport can take a long time to establish an

initial connection — up to even a minute in extreme cases, while the network topology is configured. Consequently, this transport is not recommended for use cases involving short-lived programs, but is better for long-running programs such as background daemons or agents.

While ZeroTier makes use of the host’s IP stack (and UDP in particular), this transport does not use or require an IP stack on the virtual network; thereby mitigating any considerations about IP address management.

This service uses Ethernet type 901 to transport packets. Network rules must permit this Ethernet type to pass in order to have a functional network.

Note This document assumes that the reader is familiar with ZeroTier

concepts and administration.

### Registration
Depending upon how the library was built, it may be necessary to register the transport by calling nng_zt_register(). This function returns zero on success, or an nng error value if the transport cannot be initialized for any reason.

### URI Format
This transport uses URIs using the scheme zt://, followed by a node number (ten hexadecimal digits) followed by a . delimited, and then a network address (sixteen hexadecimal digits), followed by a colon (:) and service or port number (decimal value, up to 24-bits). For example, the URI zt://fedcba9876.0123456789abdef:999 indicates that node fedcba9876 on network 0123456789abcdef is listening on port 999.

The special value * can be used in lieu of a node number to represent the node’s own node number.

Listeners may use port 0 to indicate that a suitable port number be selected automatically. Applications using this must determine the selected port number using the nng_listener_getopt() function.

### Socket Address
When using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_zt.

### Node Presence
By default this transport creates an "ephemeral" node, and used the same ephemeral node for any additional endpoints created. As this node is ephemeral, the keys associated with it and all associated data are located in memory and are discarded upon application termination. If a persistent node is desired, please see the NNG_OPT_ZT_HOME option.

It is possible for a single application to join multiple networks using the same node, or using separate nodes.

### Network Status
A ZeroTier node can be in one of the following states, which can be obtained with the NNG_OPT_ZT_NETWORK_STATUS option:

NNG_ZT_STATUS_UP

The ZeroTier network is up. This is the only state where it is possible to communicate with peers, and the only state where the network name (NNG_OPT_ZT_NETWORK_NAME) is available.

NNG_ZT_STATUS_CONFIG

The ZeroTier node is still configuring, network services are not available.

NNG_ZT_STATUS_DENIED

The node does not have permission to join the ZeroTier network.

NNG_ZT_STATUS_NOTFOUND

The ZeroTier network is not found.

NNG_ZT_STATUS_ERROR

Some other ZeroTier error has occurred; the network is not available.

NNG_ZT_STATUS_OBSOLETE

The node is running obsolete software; the network is not available.

NNG_ZT_STATUS_UNKNOWN

The network is in an unknown state. This should not happen, as it indicates that the ZeroTier software is reporting an unexpected status. The network is most likely not available.

### Transport Options
The following transport options are available:

NNG_OPT_ZT_HOME

(string) This option represents the home directory, where the transport can store (and reuse) persistent state, such as key materials, node identity, and federation membership. This option must be set before the ZeroTier transport is first used. If this value is empty, then an ephemeral ZeroTier node is created, and no persistent state is used. The default is to use an ephemeral node.

Note If this option is set to different values on different sockets,

dialers, or listeners, then separate nodes will be created. It is perfectly valid for an application to have multiple node identities in this fashion.

NNG_OPT_ZT_NWID

(uint64_t) The 64-bit ZeroTier network number (native byte order).

NNG_OPT_ZT_NODE

(uint64_t) The ZeroTier 40-bit node address (native byte order).

NNG_OPT_ZT_NETWORK_STATUS

(int) The ZeroTier network status. See Network Status for an explanation of this option.

NNG_OPT_ZT_NETWORK_NAME

(string) The name of the network as established by the ZeroTier network administrator.

NNG_OPT_ZT_CONN_TIME

(nng_duration) The time to wait between sending connection attempts, only used with dialers. The default is 500 msec.

NNG_OPT_ZT_CONN_TRIES

(int) The maximum number of attempts to try to establish a connection before reporting a timeout, and is only used with dialers. The default is 240, which results in a 2 minute timeout if NNG_OPT_ZT_CONN_TIME is at its default of 500. If the value is set to 0, then connection attempts will keep retrying forever.

NNG_OPT_ZT_PING_TIME

(nng_duration) If no traffic has been received from the ZeroTier peer after this period of time, then a ping message is sent to check if the peer is still alive.

NNG_OPT_ZT_PING_TRIES

(int) If this number of consecutive ping requests are sent to the peer with no response (and no other intervening traffic), then the peer is assumed to be dead and the connection is closed.

NNG_OPT_ZT_MTU

(size_t) The ZeroTier virtual network MTU (read-only) as configured on the network; this is the Virtual Layer 2 MTU. The headers used by this transport and the protocols consume some of this for each message sent over the network. (The transport uses 20-bytes of this, and each protocol may consume additional space, typically not more than 16-bytes.)

NNG_OPT_ZT_ORBIT

(uint64_t[2]) Write-only array of two uint64_t values, indicating the ID of a ZeroTier moon, and the node ID of the root server for that moon. (The ID may be zero if the moon ID is the same as its root server ID, which is conventional.)

NNG_OPT_ZT_DEORBIT

(uint64_t) Write-only option indicating the moon ID to deorbit. If the node is not already orbiting the moon, then this has no effect.

## SEE ALSO
nng_sockaddr_zt(5), nng(7)