---
name: "xnbd-bgctl"
section: "1"
platform: "linux"
package: "xnbd-server"
version: "0.3.0-3"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/xnbd-bgctl"
---

# xnbd-bgctl(1)

Control a server running xnbd-server(8) through its control socket

## NAME

xnbd-bgctl - Control a server running [xnbd-server(8)](/xnbd-server/8.md) through its control socket

## SYNOPSIS

**xnbd-bgctl** --query *CONTROL\_SOCKET*

**xnbd-bgctl** \[--force\] --switch *CONTROL\_SOCKET*

**xnbd-bgctl** \[--progress\] --cache-all *CONTROL\_SOCKET*

**xnbd-bgctl** --cache-all2 *CONTROL\_SOCKET*

**xnbd-bgctl** \[--exportname *NAME*\] --reconnect *CONTROL\_SOCKET* *REMOTE\_HOST* *REMOTE\_PORT*

## DESCRIPTION

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.

## OPTIONS

The following options are supported:

- **--cache-all**

  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.

- **--cache-all2**

  This command is identical to **--cache-all** but detaches the process from the terminal and is hence using a dedicated connection for data transfer. Not implemented fully yet.

- **--query**

  This command retrieves completion statistics from the proxy server instance. It returns the number of cached blocks on the server.

- **--reconnect**

  This command recovers from a lost connection by re-establishing connectivity with the origin server. This command expects two additional arguments, the *REMOTE\_HOST*, and the *REMOTE\_PORT* you want to connect to, to recover from a disconnected session.

- **--switch**

  This command stops the proxy server and restarts in target mode. All client sessions are preserved.

- **--exportname** *NAME*

  If the server supports to access devices by an identifier, use *NAME* to request access to a particular volume. This command is useful in combination with an xnbd-wrapper, not a plain xnbd-server.

- **--progress**

  Enables display of a progress bar on stderr. Disabled by default.

- **--force**

  Ignore risks, use with care. Disabled by default.

(**--shutdown**)

Deprecated alias to **--switch**, please do not use.

## POSITIONAL ARGUMENTS

The following positional options are supported:

*CONTROL\_SOCKET*

The Unix domain socket, the [xnbd-server(8)](/xnbd-server/8.md) program is listening on.

## SEE ALSO

[xnbd-server(8)](/xnbd-server/8.md), [xnbd-wrapper(8)](/xnbd-wrapper/8.md), [xnbd-wrapper-ctl(8)](/xnbd-wrapper-ctl/8.md)

## AUTHOR

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).

The xNBD userland programs have been written by Takahiro Hirofuchi (t.hirofuchi@aist.go.jp).

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.