Upload-file command¶
Uploads one file to the given bucket.
Uploads the contents of the local file, and assigns the given name to the B2 file, possibly setting options like server-side encryption and retention.
A FIFO file (such as named pipe) can be given instead of regular file.
By default, upload_file will compute the sha1 checksum of the file to be uploaded. But, if you already have it, you can provide it on the command line to save a little time.
Warning
Setting file retention mode to ‘compliance’ is irreversible - such files can only be ever deleted after their retention period passes, regardless of keys (master or not) used. This is especially dangerous when setting bucket default retention, as it may lead to high storage costs.
Content type is optional. If not set, it will be guessed.
The maximum number of upload threads to use to upload parts of a large file is specified by --threads
.
It has no effect on “small” files (under 200MB as of writing this).
Default is 10.
Each fileInfo is of the form a=b
.
By default, the file is broken into many parts to maximize upload parallelism and increase speed.
Setting --minPartSize
controls the minimal upload file part size.
Part size must be in 5MB to 5GB range.
Reference: https://www.backblaze.com/docs/cloud-storage-create-large-files-with-the-native-api
If the tqdm
library is installed, progress bar is displayed
on stderr. Without it, simple text progress is printed.
Use --noProgress
to disable progress reporting (marginally improves performance in some cases).
Use –threads to manually adjust number of threads used in the operation. Otherwise, the number of threads will be automatically chosen.
To request SSE-B2 or SSE-C encryption for destination files,
please set --destinationServerSideEncryption=SSE-B2/SSE-C
.
The default algorithm is set to AES256 which can be changed
with --destinationServerSideEncryptionAlgorithm
parameter.
Using SSE-C requires providing B2_DESTINATION_SSE_C_KEY_B64
environment variable,
containing the base64 encoded encryption key.
If B2_DESTINATION_SSE_C_KEY_ID
environment variable is provided,
it’s value will be saved as sse_c_key_id
in the
uploaded file’s fileInfo.
Setting file retention settings requires the writeFileRetentions capability, and only works in bucket
with fileLockEnabled=true. Providing --fileRetentionMode
requires providing --retainUntil
which has to
be a future timestamp, in the form of an integer representing milliseconds
since epoch. Leaving out these options results in a file retained according to bucket defaults.
Setting legal holds requires the writeFileLegalHolds capability, and only works in bucket with fileLockEnabled=true.
Use –incrementalMode to allow for incremental file uploads to safe bandwidth. This will only affect files, which have been appended to since last upload.
The --custom-upload-timestamp
, in milliseconds-since-epoch, can be used
to artificially change the upload timestamp of the file for the purpose
of preserving retention policies after migration of data from other storage.
The access to this feature is restricted - if you really need it, you’ll
need to contact customer support to enable it temporarily for your account.
Requires capability:
writeFiles
b2 upload-file [-h] [--profile PROFILE] [--quiet] [--contentType CONTENTTYPE]
[--sha1 SHA1] [--cache-control CACHE_CONTROL] [--info INFO]
[--custom-upload-timestamp CUSTOM_UPLOAD_TIMESTAMP]
[--minPartSize MINPARTSIZE] [--threads THREADS] [--noProgress]
[--destinationServerSideEncryption {SSE-B2,SSE-C}]
[--destinationServerSideEncryptionAlgorithm {AES256}]
[--legalHold {on,off}]
[--fileRetentionMode {compliance,governance}]
[--retainUntil TIMESTAMP] [--incrementalMode]
bucketName localFilePath b2FileName
Positional Arguments¶
- bucketName
name of the bucket where the file will be stored
- localFilePath
path of the local file or stream to be uploaded
- b2FileName
name file will be given when stored in B2
Named Arguments¶
- --profile
- --quiet
prevents printing any information to stdout
Default: False
- --contentType
MIME type of the file being uploaded. If not set it will be guessed.
- --sha1
SHA-1 of the data being uploaded for verifying file integrity
- --cache-control
- --info
additional file info to be stored with the file. Can be used multiple times for different information.
Default: []
- --custom-upload-timestamp
overrides object creation date. Expressed as a number of milliseconds since epoch.
- --minPartSize
minimum part size in bytes
- --threads
- --noProgress
progress will not be reported
Default: False
- --destinationServerSideEncryption
Possible choices: SSE-B2, SSE-C
- --destinationServerSideEncryptionAlgorithm
Possible choices: AES256
Default: “AES256”
- --legalHold
Possible choices: on, off
- --fileRetentionMode
Possible choices: compliance, governance
- --retainUntil
- --incrementalMode
Default: False