Skip to content

Commit 71142c1

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #233 from percona/pxb-3222-8.0
PXB-3222 Redo the option topics for xtrabackup, xbstream, xbcloud, an…
2 parents 2c56bd8 + a8e8781 commit 71142c1

11 files changed

+723
-429
lines changed

‎docs/xbcloud-binary-overview.md

+5
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,14 @@ xtrabackup and xbstream changed to 10M.
3535

3636
To adjust the chunk size use [`--read-buffer-size`](xtrabackup-option-reference.md#--read-buffer-size). To adjust the chunk size for encrypted files, use `--read-buffer-size` and [`--encrypt-chunk-size`](xtrabackup-option-reference.md#--encrypt-chunk-size).
3737

38+
3839
xbcloud has three essential operations: *put*, *get*, and *delete*. With these
3940
operations, backups are created, stored, retrieved, restored, and
4041
deleted. xbcloud operations clearly map to similar operations within
4142
the AWS Amazon S3 API.
4243

44+
For details on the command-line options, see the [xbcloud command line options].
45+
4346
The [Exponential Backoff](xbcloud-exbackoff.md) feature was implemented in Percona XtraBackup 8.0.26-18. During the backup, a chunk fails to upload or download operation; this feature adds an exponential backoff, a sleep time, and retries the operation. This feature increases the chances of completing a backup or a restore operation.
4447

4548
The [FIFO datasink](xbcloud-binary-fifo-datasink.md) feature was implemented in Percona XtraBackup 8.0.33-28. With the `FIFO` data sink feature, users with a streaming capacity of 10Gbps (typically on a Local Area Network (LAN)) can benefit from faster backups by streaming data in parallel to object storage.
@@ -300,3 +303,5 @@ ibdata1 sakila/payment.ibd \
300303

301304
$ xbstream -xv -C /storage/partial < /storage/partial/partial.xbs
302305
```
306+
307+
[xbcloud command line options]: xbcloud-options.md

‎docs/xbcloud-options.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
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+
The Swift username (X-Auth-User, specific to Swift)
29+
30+
## swift-key
31+
32+
Usage: `--swift-key`
33+
The Swift key/password (X-Auth-Key, specific to Swift)
34+
35+
## swift-container
36+
37+
Usage: `--swift-container`
38+
39+
The container to back up into (specific to Swift)
40+
41+
## parallel
42+
43+
Usage: `--parallel=N`
44+
45+
The maximum number of concurrent upload/download requests. The default value is `1`.
46+
47+
## cacert
48+
49+
Usage: `--cacert`
50+
51+
The path to the file with CA certificates
52+
53+
## insecure
54+
55+
Usage: `--insecure`
56+
57+
Do not verify the server's certificate
58+
59+
## Swift authentication options
60+
61+
The Swift specification describes several [authentication options](http://docs.openstack.org/developer/swift/overview_auth.html). The *xbcloud* tool can
62+
authenticate against keystone with API version 2 and 3.
63+
64+
## swift-auth-version
65+
66+
Usage: `--swift-auth-version`
67+
68+
Specifies the swift authentication version. The possible values are: `1.0` -
69+
TempAuth, `2.0` - Keystone v2.0, and `3` - Keystone v3. The default value is
70+
`1.0`.
71+
72+
## For v2 additional options are:
73+
74+
### swift-tenant
75+
76+
Usage: `--swift-tenant`
77+
78+
Swift tenant name
79+
80+
### swift-tenant-id
81+
82+
Usage: `--swift-tenant-id`
83+
84+
Swift tenant ID
85+
86+
### swift-region
87+
88+
Usage: `--swift-region`
89+
90+
Swift endpoint region
91+
92+
### swift-password
93+
94+
Usage: `--swift-password`
95+
96+
Swift password for the user
97+
98+
## For v3, additional options are:
99+
100+
### swift-user-id
101+
102+
Usage: `--swift-user-id`
103+
104+
Swift user ID
105+
106+
### swift-project
107+
108+
Usage: `--swift-project`
109+
110+
Swift project name
111+
112+
### swift-project-id
113+
114+
Usage: `--swift-project-id`
115+
116+
Swift project ID
117+
118+
### swift-domain
119+
120+
Usage: `--swift-domain`
121+
122+
Swift domain name
123+
124+
### swift-domain-id
125+
126+
Usage: `--swift-domain-id`
127+
128+
Swift domain ID

‎docs/xbcloud-swift.md

+7-108
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22

33
## Create a full backup with Swift
44

5+
For details on the command-line options, see the [xbcloud command-line options]
6+
57
The following example shows how to make a full backup and upload it to Swift.
68

7-
```{.bash data-prompt="$"}
9+
```{.bash
810
$ xtrabackup --backup --stream=xbstream --extra-lsndir=/tmp --target-dir=/tmp | \
911
xbcloud put --storage=swift \
1012
--swift-container=test \
@@ -16,51 +18,40 @@ full_backup
1618
```
1719

1820
The following OpenStack environment variables are also recognized and mapped automatically to the corresponding swift parameters (`--storage=swift`):
19-
20-
* OS_AUTH_URL
2121

22+
* OS_AUTH_URL
2223

2324
* OS_TENANT_NAME
2425

25-
2626
* OS_TENANT_ID
2727

28-
2928
* OS_USERNAME
3029

31-
3230
* OS_PASSWORD
3331

34-
3532
* OS_USER_DOMAIN
3633

37-
3834
* OS_USER_DOMAIN_ID
3935

40-
4136
* OS_PROJECT_DOMAIN
4237

43-
4438
* OS_PROJECT_DOMAIN_ID
4539

46-
4740
* OS_REGION_NAME
4841

49-
5042
* OS_STORAGE_URL
5143

52-
5344
* OS_CACERT
5445

5546
## Restore with Swift
5647

57-
```{.bash data-prompt="$"}
48+
```{.bash
5849
$ xbcloud get [options] <name> [<list-of-files>] | xbstream -x
5950
```
6051

6152
The following example shows how to fetch and restore the backup from Swift:
6253

63-
```{.bash data-prompt="$"}
54+
```{.bash
6455
$ xbcloud get --storage=swift \
6556
--swift-container=test \
6657
--swift-user=test:tester \
@@ -74,96 +65,4 @@ $ xbcloud delete --storage=swift --swift-user=xtrabackup \
7465
--swift-container=mybackup1 --swift-domain=Default
7566
```
7667

77-
## Command-line options
78-
79-
*xbcloud* has the following command line options:
80-
81-
### --storage(=[swift|s3|google])
82-
83-
Cloud storage option. *xbcloud* supports Swift, MinIO, and AWS S3.
84-
The default value is `swift`.
85-
86-
### --swift-auth-url()
87-
88-
The URL of the Swift cluster
89-
90-
### --swift-storage-url()
91-
92-
The xbcloud tries to get the object-store URL for a given region (if any are specified)
93-
from the keystone response. You can override that URL by passing
94-
–swift-storage-url=URL argument.
95-
96-
### --swift-user()
97-
98-
The Swift username (X-Auth-User, specific to Swift)
99-
100-
### --swift-key()
101-
102-
The Swift key/password (X-Auth-Key, specific to Swift)
103-
104-
### --swift-container()
105-
106-
The container to back up into (specific to Swift)
107-
108-
### --parallel(=N)
109-
110-
The maximum number of concurrent upload/download requests. The default value is `1`.
111-
112-
### --cacert()
113-
114-
The path to the file with CA certificates
115-
116-
### --insecure()
117-
118-
Do not verify server's certificate
119-
120-
### Swift authentication options
121-
122-
The Swift specification describes several [authentication options](http://docs.openstack.org/developer/swift/overview_auth.html). The *xbcloud* tool can
123-
authenticate against keystone with API version 2 and 3.
124-
125-
### --swift-auth-version()
126-
127-
Specifies the swift authentication version. The possible values are: `1.0` -
128-
TempAuth, `2.0` - Keystone v2.0, and `3` - Keystone v3. The default value is
129-
`1.0`.
130-
131-
For v2 additional options are:
132-
133-
### --swift-tenant()
134-
135-
Swift tenant name
136-
137-
### --swift-tenant-id()
138-
139-
Swift tenant ID
140-
141-
### --swift-region()
142-
143-
Swift endpoint region
144-
145-
### --swift-password()
146-
147-
Swift password for the user
148-
149-
For v3 additional options are:
150-
151-
### --swift-user-id()
152-
153-
Swift user ID
154-
155-
### --swift-project()
156-
157-
Swift project name
158-
159-
### --swift-project-id()
160-
161-
Swift project ID
162-
163-
### --swift-domain()
164-
165-
Swift domain name
166-
167-
### --swift-domain-id()
168-
169-
Swift domain ID
68+
[xbcloud command-line options]: xbcloud-options.md

‎docs/xbcrypt-binary-overview.md

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

6-
**Percona XtraBackup** 8.0.28-20 implements the XBCRYPT_ENCRYPTION_KEY environment variable. The 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.
6+
**Percona XtraBackup** 8.0.28-20 implements the `XBCRYPT_ENCRYPTION_KEY` environment variable. The 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.
77

8-
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:
8+
This utility has been modeled after The [xbstream binary](xbstream-binary-overview.md) to perform encryption and decryption outside of *Percona XtraBackup*. `
119

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.
29-
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.
10+
For more details on the command-line options, see [xbcrypt command-line options](xbcrypt-options.md)

0 commit comments

Comments
 (0)