mmpu(1)

👑 mmpu(1) — Manta Commands 👑

okay so this is the mmpu page, bestie. it lives in the Manta Commands section and honestly it's a whole vibe once you get it. let's go 💅

---

✨ NAME ✨

mmpu — manage manta multipart uploads 🦋

✨ SYNOPSIS ✨

mmpu [OPTION...] command [command-specific arguments]

✨ DESCRIPTION ✨

okay so picture this: mmpu lets you hang out with Manta's multipart upload API. instead of yeeting your whole object at Manta in one single PUT request, this API lets you upload an object in chunks — they're called "parts", periodt. once literally all the parts are up there, you "commit" your multipart upload and boom 💥 your uploaded object is exposed as a single file in Manta. with mmpu you can create multipart uploads, upload parts to them, and commit them or "abort" (cancel) them. you can also list non-garbage collected uploads and peek at the uploaded parts for a given MPU. the range? iconic. 🌈

the primary reference for a multipart upload is its UUID. most commands operate on multipart uploads by UUID. parts of a given upload are usually referenced by their part number — and note that it begins with the first part at 0, so yes bestie, zero-indexed, we love to see it. ⭐

the final object created by a committed multipart upload is called the "target object" of the multipart upload. also, a multipart upload is often referred to as an "MPU" or just an "upload" — iykyk. 🎀

---

💖 COMMON OPTIONS 💖

these ones are supported in, like, every single command. universal icons only:

• -a, --account login — authenticate as account (that's the login name, bestie).
• -h, --help — print a help message and dip. bye 👋
• -i, --insecure — this one explicitly allows "insecure" SSL connections and transfers. ngl, all SSL connections are attempted to be made secure by using the CA certificate bundle installed by default, so this is the "i know what i'm doing" button. 🙈
• -k, --key fingerprint — authenticate using the SSH key described by fingerprint. the key must either be in ~/.ssh or loaded in the SSH agent via ssh-add. no cap.
• --role=ROLE,ROLE,... — specify which roles to assume for the request. look at you, collecting roles like pokémon 👑
• --user user — authenticate as user under account.
• -u, --url url — Manta base URL (such as https://us-central.manta.mnx.io).
• -v, --verbose — print debug output to stderr. repeat the option to increase verbosity (yes, -vv is a thing, go off 🫶).

---

🌸 COMMANDS 🌸

the following commands and options are supported:

🎀 create [OPTIONS...] PATH

creates a multipart upload that, when committed, will be exposed as a Manta object at PATH. when this command completes successfully it prints a multipart upload UUID to stdout — save this UUID, bestie, you need it for the other commands. fr fr.

for example, if you wanted to create a multipart upload for which the target object will be stored at ~~/stor/foo.txt, you would run:

$ mmpu create ~~/stor/foo.txt

since objects created through the multipart upload API should be indistinguishable from objects created through a normal Manta PUT, the create command supports similar options that you might use for mput. for example, to create a multipart upload that has 3 copies of the target object, and stores some additional headers on the target object metadata, you would run:

$ mmpu create ~~/stor/foo.txt -c 3 -H 'content-type: text/plain' \
                                   -H 'access-control-allow-origin: *'

you may also add additional data integrity checks that will be validated for your target object when you commit your upload. for example, if you want to verify that your target object ~~/stor/foo.txt is 15728640 bytes and has the content-md5 value "FLFyNOI3UFQhtkkrjXV1Bw==", you would run:

$ mmpu create ~~/stor/foo.txt -s 15728650 \
                              -m 'FLFyNOI3UFQhtkkrjXV1Bw=='

the following options are supported on create:

• -c, --copies num_copies — specify the number of copies of the target object to store. (yes, 3 is a perfectly valid flex 💅)
• -H, --header header — specify an HTTP header to store in the target object's metadata. as with all Manta objects, you may store up to 4 KB of headers on the target object. that's the limit, don't push it 🍓
• -m, --md5 md5 — validate the content-md5 of the target object against the given md5 string. if the MD5 of the target object differs from the provided MD5 when the object is committed, the commit will fail. 😭

heads up: the behavior of this option differs from the similar option for mput. not the same creature, okay?

• -s, --size size — validate the size of the target object against size. if the size of the target object differs from this size when the object is committed, the commit will fail. 😭

🦋 upload [-f file] [OPTIONS...] MPU PART_NUM

uploads the contents of stdin, or from the file specified with -f, to the specified part for a given upload.

note that parts are zero-indexed. for example, if you wanted to upload the first part of upload be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d, and the part's contents are stored locally at ./part0.txt, you could run the following equivalent commands:

$ cat part0.txt | mmpu upload be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d 0

or:

$ mmpu upload -f part0.txt be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d 0

when this command completes successfully, it prints the etag of the part that was uploaded to stdout. save this etag too — you need it when committing the upload. collect them like stickers ✨

the following options are supported on upload:

• -f, --file file — upload the contents of file as the part, instead of the contents of stdin.
• --progress — force the progress bar to draw, even when stderr is redirected. main character progress bar energy 🔥
• -q, --quiet — do not display a progress meter. shh 🤫

💜 commit MPU [ETAG...]

commits a given upload with the parts specified. the parts are represented by their position in the argument list, which indicates their part number (with part 0 being the first argument after the upload ID, the second part the next argument after that, and so on), and their contents are represented by their etag. if the etag provided for a part does not match the etag of the part when the commit process fetches its metadata, an error will be returned. no takebacks on a mismatched etag, sorry bestie 💀

for example, if you want to commit an upload with id be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d and the following parts:

part 0: etag f14a41dc-7d28-6fdb-e07c-d54c0adcdf35
part 1: etag e2893e52-9ba3-64fe-eec9-b4663835ad01
part 2: etag 73b44fa7-fbd3-efea-b7d0-cd8098e1d928

you would run:

$ mmpu commit be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d \
              f14a41dc-7d28-6fdb-e07c-d54c0adcdf35 \
              e2893e52-9ba3-64fe-eec9-b4663835ad01 \
              73b44fa7-fbd3-efea-b7d0-cd8098e1d928

the multipart upload API does not require that you commit all parts uploaded, as long as zero or more consecutive parts are committed, and all parts meet part size restraints. so the following commands committing the same upload as above are also valid — but they would create a different target object than the first example. different vibe, different object ✨

this command would commit a zero-byte target object:

$ mmpu commit be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d

this would create an object consisting of only the first two parts:

$ mmpu commit be5f05d6-7daa-6869-d19b-c1f7fbcf6d8d \
              f14a41dc-7d28-6fdb-e07c-d54c0adcdf35 \
              e2893e52-9ba3-64fe-eec9-b4663835ad01

⚠️ once the commit process has begun for a given MPU, it cannot be aborted, or committed with a different set of parts than it was initially committed with. but you may retry the commit if needed. so like... choose your parts carefully, bestie 😭

to see the current status of an upload, use the get command.

🧚 abort MPU

aborts a multipart upload. cancelling plans, we've all been there 🙈

once an upload has begun aborting, it may not be committed, but you may retry the abort operation if needed. to see the current status of an upload, use the get command.

⭐ get MPU

fetches a JSON blob information about an upload, including its status: created, finalizing, or done (committed or aborted). a finalizing upload is one that began the process of being committed or aborted, but has not finished — either because the request is still in progress or because the request failed. it's in its liminal era 🦋

🌈 list

lists all multipart uploads for a user (note, this can also be done with a normal mfind call). note that these uploads may be in any state; their presence merely indicates they have not been garbage collected yet. living rent-free in the listing, iconic 👑

if you wish to list all parts that have been uploaded as well, you can run:

$ mmpu list -p

to see the parts of only one upload, you should use the parts command.

the following options are supported on list:

• -p, --includeParts — list parts in additional to uploads. (that's how it's worded, we're keeping it, it's cute)

🫶 parts MPU

lists all parts that have been uploaded to a given multipart upload.

---

🍓 ENVIRONMENT 🍓

• MANTA_USER — in place of -a, --account.
• MANTA_SUBUSER — in place of --user.
• MANTA_KEY_ID — in place of -k, --key.
• MANTA_ROLE — in place of --role.
• MANTA_URL — in place of -u, --url.
• MANTA_TLS_INSECURE — in place of -i, --insecure.

the shortcut ~~ is equivalent to /:login where :login is the account login name. the tilde tilde is literally so cute, obsessed 💖

---

🔥 DIAGNOSTICS 🔥

when using the -v option, diagnostics will be sent to stderr in bunyan output format. as an example of tracing all information about a request, try:

$ mmpu create -vv ~~/stor/foo 2>&1 | bunyan

look at that pipe game. chef's kiss 👑

---

💀 BUGS 💀

DSA keys do not work when loaded via the SSH agent. that's just how it is, bestie. 😭

report bugs at Github ⟨https://github.com/TritonDataCenter/node-manta/issues⟩ — they'd love to hear from you 🫶

---

and that's the whole page, no notes 💅 this mmpu(1) manual came from Manta and it's dated June 2017 — yeah, she's a little vintage, but vintage is literally a whole aesthetic, so slay 🌸✨🎀