Skip to content

Commit e8b6697

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #236 from percona/pxb-3222-innovation
PXB-3222 Redo the option topics for xtrabackup, xbsream, xbcloud, and…
2 parents 802ee2e + a16e981 commit e8b6697

7 files changed

+909
-588
lines changed

‎docs/xbcloud-options.md

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# The xbcloud command-line options
2+
3+
The xbcloud binary has the following command line options:
4+
5+
## storage
6+
7+
Usage: `--storage=[swift|s3|google]`
8+
9+
Defines the Cloud storage option. xbcloud supports Swift, MinIO, and AWS S3. The default value is `swift`.
10+
11+
## swift-auth-url
12+
13+
Usage: `--swift-auth-url`
14+
15+
The URL of the Swift cluster
16+
17+
## swift-storage-url
18+
19+
Usage: `--swift-storage-url`
20+
21+
The xbcloud tries to get the object-store URL for a given region (if any are specified)
22+
from the keystone response. You can override that URL by passing
23+
[–swift-storage-url=URL](#swift-storage-url) argument.
24+
25+
## swift-user
26+
27+
Usage: `--swift-user`
28+
29+
The Swift username (X-Auth-User, specific to Swift)
30+
31+
## swift-key
32+
33+
Usage: `--swift-key`
34+
35+
The Swift key/password (X-Auth-Key, specific to Swift)
36+
37+
## swift-container
38+
39+
Usage: `--swift-container`
40+
41+
The container to back up into (specific to Swift)
42+
43+
## parallel
44+
45+
Usage: `--parallel=N`
46+
47+
The maximum number of concurrent upload/download requests. The default value is `1`.
48+
49+
## cacert
50+
51+
Usage: `--cacert`
52+
53+
The path to the file with CA certificates
54+
55+
## insecure
56+
57+
Usage: `--insecure`
58+
59+
Do not verify the server's certificate
60+
61+
## Swift authentication options
62+
63+
The Swift specification describes several [authentication options](http://docs.openstack.org/developer/swift/overview_auth.html). The *xbcloud* tool can
64+
authenticate against keystone with API version 2 and 3.
65+
66+
## swift-auth-version
67+
68+
Usage: `--swift-auth-version`
69+
70+
Specifies the swift authentication version. The possible values are: `1.0` -
71+
TempAuth, `2.0` - Keystone v2.0, and `3` - Keystone v3. The default value is
72+
`1.0`.
73+
74+
## For v2 additional options are:
75+
76+
### swift-tenant
77+
78+
Usage: `--swift-tenant`
79+
80+
Swift tenant name
81+
82+
### swift-tenant-id
83+
84+
Usage: `--swift-tenant-id`
85+
86+
Swift tenant ID
87+
88+
### swift-region
89+
90+
Usage: `--swift-region`
91+
92+
Swift endpoint region
93+
94+
### swift-password
95+
96+
Usage: `--swift-password`
97+
98+
Swift password for the user
99+
100+
## For v3, additional options are:
101+
102+
### swift-user-id
103+
104+
Usage: `--swift-user-id`
105+
106+
Swift user ID
107+
108+
### swift-project
109+
110+
Usage: `--swift-project`
111+
112+
Swift project name
113+
114+
### swift-project-id
115+
116+
Usage: `--swift-project-id`
117+
118+
Swift project ID
119+
120+
### swift-domain
121+
122+
Usage: `--swift-domain`
123+
124+
Swift domain name
125+
126+
### swift-domain-id
127+
128+
Usage: `--swift-domain-id`
129+
130+
Swift domain ID

‎docs/xbcrypt-binary-overview.md

+2-42
Original file line numberDiff line numberDiff line change
@@ -3,47 +3,7 @@
33
To support encryption and decryption of the backups, a new tool `xbcrypt` was
44
introduced to *Percona XtraBackup*.
55

6-
The `XBCRYPT_ENCRYPTION_KEY` environment variable is only used in place of the `--encrypt_key=name` option. You can use the environment variable or command line option. If you use both, the command line option takes precedence over the value specified in the environment variable.
7-
86
This utility has been modeled after The [xbstream binary](xbstream-binary-overview.md) to perform
9-
encryption and decryption outside of *Percona XtraBackup*. `xbcrypt` has
10-
following command line options:
11-
12-
13-
### -d(, --decrypt()
14-
Decrypt data input to output.
15-
16-
17-
### -i(, --input(=name)
18-
Optional input file. If not specified, input will be read from standard
19-
input.
20-
21-
22-
### -o(, --output(=name)
23-
Optional output file. If not specified, output will be written to standard
24-
output.
25-
26-
27-
### -a(, --encrypt-algo(=name)
28-
Encryption algorithm.
7+
encryption and decryption outside of Percona XtraBackup.
298

30-
31-
### -k(, --encrypt-key(=name)
32-
Encryption key.
33-
34-
35-
### -f(, --encrypt-key-file(=name)
36-
File which contains encryption key.
37-
38-
39-
### -s(, --encrypt-chunk-size(=#)
40-
Size of working buffer for encryption in bytes. The default value is 64K.
41-
42-
43-
### --encrypt-threads(=#)
44-
This option specifies the number of worker threads that will be used for
45-
parallel encryption/decryption.
46-
47-
48-
### -v(, --verbose()
49-
Display verbose status output.
9+
The `XBCRYPT_ENCRYPTION_KEY` environment variable is only used in place of the `--encrypt_key=name` option. You can use the environment variable or command line option. If you use both, the command line option takes precedence over the value specified in the environment variable.

‎docs/xbcrypt-options.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# The xbcrypt command-line options
2+
3+
The `xbcrypt` binary has the following command line options:
4+
5+
### encrypt-algo
6+
7+
usage: `-a` `--encrypt-algo`
8+
9+
Defines the name of the encryption algorithm.
10+
11+
### decrypt
12+
13+
usage: `-d` `--decrypt`
14+
15+
Decrypt data input to output.
16+
17+
### encrypt-chunk-size
18+
19+
usage: `-s` `--encrypt-chunk-size`
20+
21+
Defines the size of the working buffer for encryption in bytes. The default value is `64000`.
22+
23+
### encrypt-key
24+
25+
usage: `-k` `--encrypt-key`
26+
27+
The name of the encryption key.
28+
29+
### encrypt-key-file
30+
31+
usage: `-f` `--encrypt-key-file`
32+
33+
The name of the file that contains the encryption key.
34+
35+
### encrypt-threads
36+
37+
usage: `--encrypt-threads`
38+
39+
This option specifies the number of worker threads used for
40+
parallel encryption/decryption.
41+
42+
### input
43+
44+
usage: `-i` `--input`
45+
46+
Defines the name of the optional input file. If the name is not specified, the input reads from the standard input.
47+
48+
### output
49+
50+
usage: `-o` `--output`
51+
52+
Defines the name of the optional output file. If this name is not specified, the output is written to the standard output.
53+
54+
### verbose
55+
56+
usage: `-v` `--verbose`
57+
58+
Display status in verbose mode.

‎docs/xbstream-binary-overview.md

+10-69
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,17 @@
11
# The xbstream binary overview
22

3-
To support simultaneous compression and streaming, a new custom streaming
4-
format called xbstream was introduced to Percona XtraBackup in addition to
5-
the TAR format. That was required to overcome some limitations of traditional
6-
archive formats such as tar, cpio and others which did not allow streaming
7-
dynamically generated files, for example dynamically compressed files. Other
8-
advantages of xbstream over traditional streaming/archive format include
9-
ability to stream multiple files concurrently (so it is possible to use
3+
To support simultaneous compression and streaming, the xbstream binary was added to Percona XtraBackup, along with the xbstream format and tar format. These additions were required to overcome some limitations of traditional
4+
archive formats such as tar, cpio, and others, which did not allow streaming
5+
dynamically generated files.
6+
7+
Other advantages of xbstream over traditional streaming/archive format include streaming multiple files concurrently (so it is possible to use
108
streaming in the xbstream format together with the –parallel option) and more
119
compact data storage.
1210

13-
This utility has a tar-like interface:
14-
15-
* with the `-x` option it extracts files from the stream read from its
16-
standard input to the current directory unless specified otherwise with the
17-
`-c` option. The parallel extraction is supported with the `--parallel`
18-
option.
19-
20-
* with the `-c` option it streams files specified on the command line to its
21-
standard output.
22-
23-
* with the `--decrypt=ALGO` option specified xbstream will automatically
24-
decrypt encrypted files when extracting input stream. Supported values for
25-
this option are: `AES128`, `AES192`, and `AES256`. Either
26-
`--encrypt-key` or `--encrypt-key-file` options must be specified to
27-
provide encryption key, but not both.
28-
29-
* with the `--encrypt-threads` option you can specify the number of threads
30-
for parallel data encryption. The default value is `1`.
31-
32-
* the `--encrypt-key` option is used to specify the encryption key that will
33-
be used. It can’t be used with `--encrypt-key-file` option because they
34-
are mutually exclusive.
35-
36-
* the `--encrypt-key-file` option is used to specify the file that contains
37-
the encryption key. It can’t be used with `--encrypt-key` option.
38-
because they are mutually exclusive.
39-
40-
The utility also tries to minimize its impact on the OS page cache by using the
41-
appropriate `posix_fadvise()` calls when available.
42-
43-
When compression is enabled with *xtrabackup* all data is being compressed,
44-
including the transaction log file and meta data files, using the specified
45-
compression algorithm. Percona XtraBackup supports the following compression algorithms:
46-
47-
## Zstandard (ZSTD)
48-
49-
The Zstandard (ZSTD) is a fast lossless compression algorithm that targets real-time compression scenarios and better compression ratios. `ZSTD` is the default compression algorithm for the `--compress` option.
50-
51-
To compress files using the `ZSTD` compression algorithm, use the `--compress` option:
52-
53-
```{.bash data-prompt="$"}
54-
$ xtrabackup --backup --compress --target-dir=/data/backup
55-
```
56-
57-
The resulting files have the `\*.zst` format.
58-
59-
You can specify `ZSTD` compression level with the [`--compress-zstd-level(=#)`](xtrabackup-option-reference.md#compress-zstd-level) option. The default value is `1`.
60-
61-
```{.bash data-prompt="$"}
62-
$ xtrabackup –backup –compress –compress-zstd-level=1 –target-dir=/data/backup
63-
```
64-
65-
## lz4
66-
67-
To compress files using the `lz4` compression algorithm, set the `--compress` option to `lz4`:
68-
69-
```{.bash data-prompt="$"}
70-
$ xtrabackup --backup --compress=lz4 --target-dir=/data/backup
71-
```
72-
73-
The resulting files have the `\*.lz4` format.
11+
For details on the command-line options, see [xbcloud command-line options]. When available, the utility tries to minimize its impact on the OS page cache by using the appropriate `posix_fadvise()` calls.
7412

75-
To decompress files, use the `--decompress` option.
13+
When compression is enabled with xtrabackup all data is compressed,
14+
including the transaction log file and metadata files, using the specified
15+
compression algorithm. Read more about supported compression algorithms in the [Create a compressed backup](create-compressed-backup.md) document.
7616

17+
[xbcloud command-line options]: xbcloud-options.md

‎docs/xbstream-options.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# The xbstream command-line options
2+
3+
This utility has a tar-like interface.
4+
5+
6+
The xbstream binary has the following options:
7+
8+
## c
9+
10+
Usage: `-c`
11+
12+
Streams files specified on the command line to its standard output.
13+
14+
## decrypt
15+
16+
Usage: `--decrypt=ALGO`
17+
18+
Specifies that xbstream automatically decrypts encrypted files when extracting input stream. The supported values are: `AES128`, `AES192`, and `AES256`.
19+
20+
You can specify either `--encrypt-key` or `--encrypt-key-file` to provide the encryption key, but do not use both options.
21+
22+
## encrypt-key
23+
24+
Usage: `--encrypt-key`
25+
26+
Specify the encryption key used. Do not use this option with `--encrypt-key-file`; the options are mutually exclusive.
27+
28+
## encrypt-key-file
29+
30+
Usage: `--encrypt-key-file`
31+
32+
33+
Specify the file that contains the encryption key. Do not use this option with `--encrypt-key`; the options are mutually exclusive.
34+
35+
## encrypt-threads
36+
37+
Usage: `--encrypt-threads`
38+
39+
Specify the number of threads for parallel data encryption. The default value is `1`.
40+
41+
## x
42+
43+
Usage: `-x`
44+
45+
Extracts files from the stream read from its
46+
standard input to the current directory unless specified otherwise with the
47+
`-c` option. Support for parallel extraction with the `--parallel`
48+
option

0 commit comments

Comments
 (0)