diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1 index bbf5280..1f288d6 100644 --- a/doc/manpages/swift.1 +++ b/doc/manpages/swift.1 @@ -130,14 +130,33 @@ programs, such as jq. capabilities \-\-json .RE -\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR +\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fItime\fR \fIpath\fR \fIkey\fR .RS 4 Generates a temporary URL allowing unauthenticated access to the Swift object -at the given path, using the given HTTP method, for the given number of -seconds, using the given TempURL key. With the optional \-\-prefix\-based option a -prefix-based URL is generated. If optional \-\-absolute argument is -provided, seconds is instead interpreted as a Unix timestamp at which the URL -should expire. \fBExample\fR: tempurl GET $(date \-d "Jan 1 2016" +%s) +at the given path, using the given HTTP method, for the given time, +using the given TempURL key. + +The time can be specified either as an integer +denoting the amount of seconds the temporary URL is valid, or as an ISO 8601 +timestamp in one of following formats: Complete date: YYYY\-MM\-DD (eg 1997\-07\-16), +complete date plus hours, minutes and seconds: YYYY\-MM\-DDThh:mm:ss +(eg 1997\-07\-16T19:20:30) or complete date plus hours, minutes and seconds with +UTC designator: YYYY\-MM\-DDThh:mm:ssZ (eg 1997\-07\-16T19:20:30Z). Be aware that +if you do not use the latter format, the timestamp is generated using your locale +timezone. If the first format is used, the time part used will equal to 00:00:00. + +With the \-\-prefix\-based option a +prefix-based URL is generated. + +The option \-\-iso8601 provides ISO 8601 UTC timestamps +instead of Unix timestamps inside the generated URL. + +If optional \-\-absolute argument is +provided and the time argument is specified in seconds, the seconds are +interpreted as a Unix timestamp at which the URL +should expire. + +\fBExample\fR: tempurl GET $(date \-d "Jan 1 2016" +%s) /v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key \-\-absolute .RE diff --git a/doc/source/cli.rst b/doc/source/cli.rst index b107448..8d80d1b 100644 --- a/doc/source/cli.rst +++ b/doc/source/cli.rst @@ -228,18 +228,39 @@ Capabilities Tempurl ------- - ``tempurl [command-options] [method] [seconds] [path] [key]`` + ``tempurl [command-options] [method] [time] [path] [key]`` Generates a temporary URL for a Swift object. ``method`` option sets an HTTP method to - allow for this temporary URL that is usually 'GET' or 'PUT'. ``seconds`` option sets - the amount of time in seconds the temporary URL will be valid for; or, if ``--absolute`` - is passed, the Unix timestamp when the temporary URL will expire. ``path`` option sets - the full path to the Swift object. Example: ``/v1/AUTH_account/c/o``. ``key`` option is + allow for this temporary URL that is usually ``GET` or ``PUT``. ``time`` option sets + the amount of time the temporary URL will be valid for. + ``time`` can be specified as an integer, denoting the number of seconds + from now on until the URL shall be valid; or, if ``--absolute`` + is passed, the Unix timestamp when the temporary URL will expire. + But beyond that, ``time`` can also be specified as an ISO 8601 timestamp + in one of following formats: + + i) Complete date: YYYY-MM-DD (eg 1997-07-16) + + ii) Complete date plus hours, minutes and seconds: + YYYY-MM-DDThh:mm:ss + (eg 1997-07-16T19:20:30) + + iii) Complete date plus hours, minutes and seconds with UTC designator: + YYYY-MM-DDThh:mm:ssZ + (eg 1997-07-16T19:20:30Z) + + Please be aware that if you don't provide the UTC designator (i.e., Z) + the timestamp is generated using your local timezone. If only a date is + specified, the time part used will equal to ``00:00:00``. + + ``path`` option sets the full path to the Swift object. + Example: ``/v1/AUTH_account/c/o``. ``key`` option is the secret temporary URL key set on the Swift cluster. To set a key, run ``swift post -m "Temp-URL-Key: "``. To generate a prefix-based temporary URL use the ``--prefix-based`` option. This URL will contain the path to the prefix. Do not forget to append the desired objectname at the end of the path portion (and before the - query portion) before sharing the URL. + query portion) before sharing the URL. It is possible to use ISO 8601 UTC timestamps within the + URL by using the ``--iso8601`` option. Auth ---- diff --git a/swiftclient/shell.py b/swiftclient/shell.py index 4a8a356..841ed6e 100755 --- a/swiftclient/shell.py +++ b/swiftclient/shell.py @@ -1224,8 +1224,8 @@ def st_auth(parser, args, thread_manager): print('export OS_AUTH_TOKEN=%s' % sh_quote(token)) -st_tempurl_options = '''[--absolute] [--prefix-based] - ''' +st_tempurl_options = '''[--absolute] [--prefix-based] [--iso8601] +