'\" t
.\"     Title: xnbd-bgctl
.\"    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\-BGCTL" "1" "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-bgctl \- Control a server running xnbd\-server(8) through its control socket
.SH "SYNOPSIS"
.sp
\fBxnbd\-bgctl\fR \-\-query \fICONTROL_SOCKET\fR
.sp
\fBxnbd\-bgctl\fR [\-\-force] \-\-switch \fICONTROL_SOCKET\fR
.sp
\fBxnbd\-bgctl\fR [\-\-progress] \-\-cache\-all \fICONTROL_SOCKET\fR
.sp
\fBxnbd\-bgctl\fR \-\-cache\-all2 \fICONTROL_SOCKET\fR
.sp
\fBxnbd\-bgctl\fR [\-\-exportname \fINAME\fR] \-\-reconnect \fICONTROL_SOCKET\fR \fIREMOTE_HOST\fR \fIREMOTE_PORT\fR
.SH "DESCRIPTION"
.sp
With the xnbd\-bgctl command you can connect to an xnbd\-server control channel and instruct it to act as directed\&. You may pass an argument to the control program which is then forwarded, on your behalf, to the server instance\&.
.SH "OPTIONS"
.sp
The following options are supported:
.PP
\fB\-\-cache\-all\fR
.RS 4
If the remote xnbd\-server acts as proxy server, this command instructs the controlling xnbd\-server instance to cache all blocks on its associated block disk\&. Upon completion the controlled xnbd\-server instance holds all data from the origin instance and it is no longer necessary to act as proxy\&.
.RE
.PP
\fB\-\-cache\-all2\fR
.RS 4
This command is identical to
\fB\-\-cache\-all\fR
but detaches the process from the terminal and is hence using a dedicated connection for data transfer\&. Not implemented fully yet\&.
.RE
.PP
\fB\-\-query\fR
.RS 4
This command retrieves completion statistics from the proxy server instance\&. It returns the number of cached blocks on the server\&.
.RE
.PP
\fB\-\-reconnect\fR
.RS 4
This command recovers from a lost connection by re\-establishing connectivity with the origin server\&. This command expects two additional arguments, the
\fIREMOTE_HOST\fR, and the
\fIREMOTE_PORT\fR
you want to connect to, to recover from a disconnected session\&.
.RE
.PP
\fB\-\-switch\fR
.RS 4
This command stops the proxy server and restarts in target mode\&. All client sessions are preserved\&.
.RE
.PP
\fB\-\-exportname\fR \fINAME\fR
.RS 4
If the server supports to access devices by an identifier, use
\fINAME\fR
to request access to a particular volume\&. This command is useful in combination with an xnbd\-wrapper, not a plain xnbd\-server\&.
.RE
.PP
\fB\-\-progress\fR
.RS 4
Enables display of a progress bar on stderr\&. Disabled by default\&.
.RE
.PP
\fB\-\-force\fR
.RS 4
Ignore risks, use with care\&. Disabled by default\&.
.RE
.PP
(\fB\-\-shutdown\fR)
.RS 4
Deprecated alias to
\fB\-\-switch\fR, please do not use\&.
.RE
.SH "POSITIONAL ARGUMENTS"
.sp
The following positional options are supported:
.PP
\fICONTROL_SOCKET\fR
.RS 4
The Unix domain socket, the xnbd\-server(8) program is listening on\&.
.RE
.SH "SEE ALSO"
.sp
xnbd\-server(8), xnbd\-wrapper(8), xnbd\-wrapper\-ctl(8)
.SH "AUTHOR"
.sp
The NBD kernel module and the NBD tools have been written by Pavel Macheck (pavel@ucw\&.cz) and is now maintained by Paul Clements (Paul\&.Clements@steeleye\&.com)\&.
.sp
The xNBD userland programs have been written by Takahiro Hirofuchi (t\&.hirofuchi@aist\&.go\&.jp)\&.
.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\&.