'\" t
.\"     Title: xnbd-register
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 02/12/2014
.\"    Manual: xNBD Manual
.\"    Source: xNBD 0.3.0
.\"  Language: English
.\"
.TH "XNBD\-REGISTER" "8" "02/12/2014" "xNBD 0\&.3\&.0" "xNBD Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
xnbd-register \- Restore xNBD sessions upon boot
.SH "SYNOPSIS"
.sp
\fBxnbd\-register\fR [\fIOPTIONS\fR] \-\-start
.sp
\fBxnbd\-register\fR [\fIOPTIONS\fR] \-\-stop
.sp
\fBxnbd\-register\fR [\fIOPTIONS\fR] \-\-restart
.sp
\fBxnbd\-register\fR [\fIOPTIONS\fR] \-\-status
.SH "DESCRIPTION"
.sp
With the xnbd\-register command one can restore xnbd\-wrapper and xnbd\-client sessions based on a configuration file\&. This is useful to start client, wrapper or both upon boot\&.
.sp
To achieve this, xnbd\-register reads a semi\-structured configuration file located in /etc/xnbd\&.conf\&. See below for format hints\&.
.SH "OPTIONS"
.sp
The following options are supported:
.PP
\fB\-\-start\fR
.RS 4
Start devices configured in the configuration files\&. If the configuration files describes volumes, xnbd\-register will try to establish a client connection to the configured wrapper instance\&.

Alternatively, xnbd\-register will start sharing configured volumes by starting an xnbd\-wrapper super server\&.
.RE
.PP
\fB\-\-status\fR
.RS 4
Retrieve wrapper status from a running xnbd\-wrapper command, if applicable\&.
.RE
.PP
\fB\-\-stop\fR
.RS 4
Analogous to the start option, the stop argument will stop all xnbd connection, being client or wrapper instances\&.
.RE
.PP
\fB\-\-restart\fR
.RS 4
Restart all xnbd instances, being client or wrapper
.RE
.PP
\fB\-\-config\fR \fIFILE\fR
.RS 4
Config file to use\&. Defaults to /etc/xnbd\&.conf\&.
.RE
.PP
\fB\-\-quiet\fR
.RS 4
Do not produce verbose output
.RE
.SH "CONFIGURATION FILE"
.sp
xnbd\-register will read its defaults from /etc/xnbd\&.conf\&. This is a semi\-structured configuration file, describing client and wrapper connections that are supposed to be restored upon start of the system\&.
.sp
The syntax of the file is a JSON data structure, allowing comments starting with a hash key ("#")\&. Two types of objects are recognized: xnbd volumes and a wrapper instance\&. xnbd volumes are indexed by the supposed devices name\&. This is, to restore /dev/nbd0 an object named "nbd0" must be configured\&. Valid arguments are host, name and port\&. So, for example, this is to configure /dev/nbd0 connecting to localhost on port 8520\&. If present, identify the shared device by the configured logical name:
.sp
.if n \{\
.RS 4
.\}
.nf
"nbd0": {
    "host": "127\&.0\&.0\&.1",
    "port": 8520,
    "name": "name"
}
.fi
.if n \{\
.RE
.\}
.sp
Similarly, a wrapper instance configures an xnbd\-wrapper\&. Valid options are:
.PP
\fBaddress\fR
.RS 4
Specifies the listening address
.RE
.PP
\fBport\fR
.RS 4
Specifies the listening port
.RE
.PP
\fBsocket\fR
.RS 4
Specifies the listening socket for the control channels
.RE
.PP
\fBlogpath\fR
.RS 4
Specifies the log path where logging output is being redirected to
.RE
.PP
\fBvolumes\fR
.RS 4
A mapping of volumes which are exported\&. Mapping keys are export names, mapping values are disk image paths\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
"wrapper": {
    "address": "127\&.0\&.0\&.1",
    "port": 8520,
    "socket": "/var/run/xnbd\&.ctl",
    "logpath": "/var/log/xnbd\&.log",
    "volumes": {
        "one": "/dev/volume",
        "two": "/dev/sdb1",
        "three": "/var/lib/image\&.file",
    }
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
xnbd\-wrapper(8), xnbd\-client(1)
.SH "AUTHOR"
.sp
xnbd\-register was written by Arno Toell (arno@debian\&.org) for the Debian GNU/Linux system\&.
.sp
This manual page was written by Arno Toell (arno@debian\&.org) for the Debian GNU/Linux system (but may be used by others)\&. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation\&.