1nbdkit-S3-plugin(1) NBDKIT nbdkit-S3-plugin(1)
2
3
4
6 nbdkit-S3-plugin - open disk images stored in Amazon S3 or Ceph
7
9 nbdkit S3 [access-key=...] [secret-key=...] [session-token=...]
10 [endpoint-url=...]
11 bucket=BUCKET key=FILENAME
12
14 "nbdkit-S3-plugin" is a plugin for nbdkit(1) which lets you open single
15 files stored in Amazon S3 or Ceph as disk images.
16
17 Currently it only allows read access, although write access may be
18 added in future.
19
20 This plugin uses the Python Amazon Web Services SDK called Boto3.
21
23 nbdkit S3 endpoint-url=https://ceph.example.com \
24 bucket=MY-BUCKET key=disk.img
25
27 access-key=ACCESS_KEY
28 secret-key=SECRET_KEY
29 session-token=SESSION_TOKEN
30 The AWS credentials may be specified on the command line using
31 these parameters, but it is more secure to pass them using files
32 (see "CREDENTIALS" below).
33
34 endpoint-url=ENDPOINT
35 If accessing Ceph or another compatible S3 service, provide the
36 endpoint URL through this parameter.
37
38 bucket=BUCKET
39 The bucket containing the file. This parameter is required.
40
41 key=FILENAME
42 The file name within the bucket. This parameter is required.
43
45 Although AWS credentials can be passed to nbdkit on the command line,
46 this is not secure since a user on the same machine could read them
47 using ps(1).
48
49 A better way is to pass the credentials through the ~/.aws/credentials
50 file. This takes the form:
51
52 [default]
53 aws_access_key_id = XXX
54 aws_secret_access_key = YYY
55
56 [profile]
57 aws_access_key_id = XXX
58 aws_secret_access_key = YYY
59
60 Different profiles from the file can be selected by setting the
61 "AWS_PROFILE" environment variable.
62
63 There is much more information about credentials in the Boto3
64 documentation.
65
67 s3fs-fuse (https://github.com/s3fs-fuse/s3fs-fuse) presents a whole S3
68 bucket as a FUSE filesystem, with each object in the bucket
69 corresponding to a single file. It is therefore quite different from
70 this plugin which turns a single S3 object into a block device.
71
73 $plugindir/nbdkit-S3-plugin
74 The plugin.
75
76 Use "nbdkit --dump-config" to find the location of $plugindir.
77
78 $HOME/.aws/credentials
79 AWS credentials can be passed to boto3 using this file.
80
82 "AWS_*"
83 Boto3 reads some credential information from "AWS_*" environment
84 variables.
85
87 "nbdkit-S3-plugin" first appeared in nbdkit 1.24.
88
90 nbdkit(1), nbdkit-plugin(3), nbdkit-python-plugin(3),
91 https://pypi.org/project/boto3/,
92 https://boto3.amazonaws.com/v1/documentation/api/latest/index.html,
93 https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.
94
96 Richard W.M. Jones
97
99 Copyright (C) 2020 Red Hat Inc.
100
102 Redistribution and use in source and binary forms, with or without
103 modification, are permitted provided that the following conditions are
104 met:
105
106 • Redistributions of source code must retain the above copyright
107 notice, this list of conditions and the following disclaimer.
108
109 • Redistributions in binary form must reproduce the above copyright
110 notice, this list of conditions and the following disclaimer in the
111 documentation and/or other materials provided with the
112 distribution.
113
114 • Neither the name of Red Hat nor the names of its contributors may
115 be used to endorse or promote products derived from this software
116 without specific prior written permission.
117
118 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
119 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
120 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
121 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
122 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
123 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
124 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
125 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
126 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
127 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
128 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
129
130
131
132nbdkit-1.25.8 2021-05-25 nbdkit-S3-plugin(1)