diff --git a/command/fs.go b/command/fs.go index 154f34e2f..e2f99bc0e 100644 --- a/command/fs.go +++ b/command/fs.go @@ -55,6 +55,10 @@ FS Specific Options: -stat Show file stat information instead of displaying the file, or listing the directory. + -f + Causes the output to not stop when the end of the file is reached, but + rather to wait for additional output. + -tail Show the files contents with offsets relative to the end of the file. If no offset is given, -n is defaulted to 10. @@ -65,11 +69,6 @@ FS Specific Options: -c Sets the tail location in number of bytes relative to the end of the file. - - -f - Causes the output to not stop when the end of the file is reached, but - rather to wait for additional output. - ` return strings.TrimSpace(helpText) } diff --git a/website/source/docs/commands/fs.html.md.erb b/website/source/docs/commands/fs.html.md.erb index 3443d2360..1df258940 100644 --- a/website/source/docs/commands/fs.html.md.erb +++ b/website/source/docs/commands/fs.html.md.erb @@ -9,24 +9,58 @@ description: > # Command: fs The `fs` command allows a user to navigate an allocation directory on a Nomad -client. The following functionalities are available - `cat`, `ls` and `stat` +client. The following functionalities are available - `cat`, `tail`, `ls` and +`stat`. -`cat`: If the target path is a file, Nomad will cat the target path. -`ls`: If the target path is a directory, Nomad displays the name of a file and directories and their associated information. -`stat`: If the `-stat` flag is used, Nomad will Display information about a file. +* `cat`: If the target path is a file, Nomad will `cat` the file. +* `tail`: If the target path is a file and `-tail` flag is specified, Nomad will + `tail` the file. +* `ls`: If the target path is a directory, Nomad displays the name of a file and + directories and their associated information. +* `stat`: If the `-stat` flag is used, Nomad will display information about a + file. ## Usage ``` -nomad fs -nomad fs -stat +nomad fs [options] ``` -A valid allocation id is necessary unless `-job` is specified and the path is relative to the root of the allocation directory. -The path is optional and it defaults to `/` of the allocation directory +This command accepts a path and single allocation ID unless the `-job` flag is +specified, in which case an allocation is chosen for the given job. The path is +relative to the root of the allocation directory. The path is optional and it +defaults to `/` of the allocation directory +# +## General Options + +<%= general_options_usage %> + +## Fs Options + +* `-H`: Machine friendly output. + +* `-verbose`: Display verbose output. + +* `-job`: Use a random allocation from the specified job, prefering a running +allocation. + +* `-stat`: Show stat information instead of displaying the file, or listing the +directory. + +* `-f`: Causes the output to not stop when the end of the file is reached, but +rather to wait for additional output. + +* `-tail`: Show the files contents with offsets relative to the end of the file. +If no offset is given, -n is defaulted to 10. + +* `-n`: Sets the tail location in best-efforted number of lines relative to the +end of the file. + +* `-c`: Sets the tail location in number of bytes relative to the end of the file. ## Examples +``` $ nomad fs eb17e557 Mode Size Modified Time Name drwxrwxr-x 4096 28 Jan 16 05:39 UTC alloc/ @@ -46,17 +80,27 @@ Mode Size Modified Time Name $ nomad fs redis/local/redis.stdout -6710:C 27 Jan 22:04:03.794 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf -6710:M 27 Jan 22:04:03.795 * Increased maximum number of open files to 10032 (it was originally set to 256). +foobar +baz -## Using Job-ID instead of Alloc-ID +$ nomad fs -tail -f -n 3 redis/local/redis.stdout +foobar +baz +bam + +``` -Passing `-job` into one of the `fs` commands will allow the `fs` command to randomly select an allocation ID from the specified job. +## Using Job ID instead of Allocation ID + +Passing `-job` into one of the `fs` commands will allow the `fs` command to +randomly select an allocation ID from the specified job. ``` nomad fs -job ``` -Nomad will prefer to select a running allocation ID for the job, but if no running allocations for the job are found, Nomad will use a dead allocation. +Nomad will prefer to select a running allocation ID for the job, but if no +running allocations for the job are found, Nomad will use a dead allocation. -This can be useful for debugging a job that has multiple allocations, and it's not really required to use a specific allocation ID. \ No newline at end of file +This can be useful for debugging a job that has multiple allocations, and it's +not really required to use a specific allocation ID. diff --git a/website/source/docs/http/client-fs.html.md b/website/source/docs/http/client-fs.html.md index 24e404214..c1b9d130e 100644 --- a/website/source/docs/http/client-fs.html.md +++ b/website/source/docs/http/client-fs.html.md @@ -54,6 +54,85 @@ allocation was placed. +
+
Description
+
+ Stream contents of a file in an allocation directory. +
+ +
Method
+
GET
+ +
URL
+
`/v1/client/fs/stream/`
+ +
Parameters
+
+
    +
  • + path + required + The path relative to the root of the allocation directory. It + defaults to `/` +
    • +
  • + offset + The offset to start streaming from. Defaults to 0. +
    • +
  • + origin + Origin can be either "start" or "end" and applies the offset relative to + either the start or end of the file respectively. Defaults to "start". +
    • +
+
+ +
Returns
+
+ + ``` +... + { + "File":"alloc/logs/redis.stdout.0", + "Offset":3604480 + "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." + } + { + "File":"alloc/logs/redis.stdout.0", + "FileEvent": "file deleted" + } + ``` + +
+ + +
Field Reference
+
+ The return value is a stream of frames. These frames contain the following + fields: + +
    +
  • + Data + A base64 encoding of the bytes being streamed. +
    • +
  • + FileEvent + An event that could cause a change in the streams position. The possible + values are "file deleted" and "file truncated". +
    • +
  • + Offset + Offset is the offset into the stream. +
    • +
  • + File + The name of the file being streamed. +
    • +
+
+
+
Description