The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
disbatch-4.103
River stage zero No dependents
++
/ disbatch

NAME

disbatch - CLI to the Disbatch Command Interface (DCI).

VERSION

version 4.103

SYNOPSIS

    disbatch [<arguments>] <command> [<command arguments>]

ARGUMENTS

--url <URL>

URL for the DCI you wish to connect to. Default is http://localhost:8080.

--username <username>

DCI username

--password <password>

DCI password

--help

Display this message

--ssl_ca_file <ssl_ca_file>

Path to the SSL CA file. Needed if using SSL with a private CA.

--disable_ssl_verification

Disables hostname verification if SSL is used.

Only used if --ssl_ca_file is not used.

--config <config_file>

Path to Disbatch config file. Default is /etc/disbatch/config.json.

Only used if neither --ssl_ca_file nor --disable_ssl_verification is used.

Note: the SSL settings in the Disbatch config file are for MongoDB, but ideally if using SSL with MongoDB, then it is also being used with the DCI.

COMMANDS

plugins

List all allowed plugin names.

  $ disbatch plugins
  Disbatch::Plugin::Demo
queues

List all queues this disbatch server processes.

  $ disbatch queues
  ID                       | Plugin                 | Name | Threads | Queued | Running | Completed |
  -------------------------+------------------------+------+---------+--------+---------+-----------+-
  56eade3aeb6af81e0123ed21 | Disbatch::Plugin::Demo | demo | 0       | 0      | 0       | 0         |

  1 total queues.

Note: status is an alias for queues.

create-queue <name> <plugin>

Create a new queue.

  $ disbatch create-queue fizz Disbatch::Plugin::Demo
  Created queue fizz: 579a6735eb6af83e5a5297d5

Error examples:

  $ disbatch create-queue
  Error posting http://localhost:8080/queues (400 Bad Request): {"plugin":"","error":"Unknown plugin"}
  $ disbatch create-queue test
  Error posting http://localhost:8080/queues (400 Bad Request): {"plugin":"","error":"Unknown plugin"}
  $ disbatch create-queue test Disbatch::Plugin::Fake
  Error posting http://localhost:8080/queues (400 Bad Request): {"plugin":"Disbatch::Plugin::Fake","error":"Unknown plugin"}
update-queue <queue> <field> <value> [<field> <value> ...]

Change a field's value in a queue. Valid fields are name, plugin, and threads.

  $ disbatch update-queue 579a6735eb6af83e5a5297d5 name buzz
  Updated queue 579a6735eb6af83e5a5297d5: {"name":"buzz"}

Error examples:

  $ disbatch update-queue 579a6eaeeb6af87dc52d17e1
  Error posting http://localhost:8080/queues/579a6eaeeb6af87dc52d17e1 (400 Bad Request): {"error":"no params"}
  $ disbatch update-queue 579a6eaeeb6af87dc52d17e1 bad field
  Error posting http://localhost:8080/queues/579a6eaeeb6af87dc52d17e1 (400 Bad Request): {"error":"unknown param","param":"bad"}
  $ disbatch update-queue 579a6eaeeb6af87dc52d17e1 threads
  Must pass an even number of arguments as key/value pairs
  $ disbatch update-queue 579a6eaeeb6af87dc52d17e1 threads zero
  Error posting http://localhost:8080/queues/579a6eaeeb6af87dc52d17e1 (400 Bad Request): {"error":"threads must be a non-negative integer"}
  $ disbatch update-queue 579a6eaeeb6af87dc52d17e1 plugin Disbatch::Plugin::Fake
  Error posting http://localhost:8080/queues/579a6eaeeb6af87dc52d17e1 (400 Bad Request): {"plugin":"Disbatch::Plugin::Fake","error":"unknown plugin"}

  $ disbatch update-queue 579a7059eb6af87dcc6ef4e3 threads 0
  Error posting http://localhost:8080/queues/579a7059eb6af87dcc6ef4e3 (400 Bad Request): {"MongoDB::UpdateResult":{"matched_count":0,"upserted_id":null,"write_concern_errors":[],"write_errors":[],"modified_count":0},"error":"MongoDB::UpdateResult=HASH(0x401de18)"}
  $ disbatch update-queue 579a7059eb6af87dcc6ef4e3 name demo
  Error posting http://localhost:8080/queues/579a7059eb6af87dcc6ef4e3 (400 Bad Request): {"MongoDB::UpdateResult":{"matched_count":0,"upserted_id":null,"write_concern_errors":[],"write_errors":[],"modified_count":0},"error":"MongoDB::UpdateResult=HASH(0x401de18)"}
delete-queue <queue>

Delete a queue.

  $ disbatch delete-queue 579a6735eb6af83e5a5297d5
  Deleted queue 579a6735eb6af83e5a5297d5
  $ disbatch delete-queue fizz
  Deleted queue fizz

Error examples:

  $ disbatch delete-queue 579a6eaeeb6af87dc52d17e1
  Error deleting http://localhost:8080/queues/579a6eaeeb6af87dc52d17e1 (400 Bad Request): {"error":"MongoDB::DeleteResult=HASH(0x35344b8)","MongoDB::DeleteResult":{"deleted_count":0,"write_concern_errors":[],"write_errors":[]}}
  $ disbatch delete-queue fizz
  Error deleting http://localhost:8080/queues/fizz (400 Bad Request): {"error":"MongoDB::DeleteResult=HASH(0x3106520)","MongoDB::DeleteResult":{"deleted_count":0,"write_concern_errors":[],"write_errors":[]}}
create-task <queue> [<key> <value> ...]

Creates a task in the specified queue with the given params.

  $ disbatch create-task 579a49d6eb6af83e5b4ceec1 user1 ashley user2 ashley
  Created 1 tasks in queue 579a49d6eb6af83e5b4ceec1
  579a67b3eb6af83e612d8c58

Error examples:

  $ disbatch create-task
  Queue name not given
create-tasks <queue> <array_of_params>

Creates multiple tasks in the specified queue with the given params.

  $ disbatch create-tasks 579a49d6eb6af83e5b4ceec1 '[{"fizz":1}]'
  Created 1 tasks in queue 579a49d6eb6af83e5b4ceec1
  579a67dbeb6af83e5930fc72

Error examples:

  $ disbatch create-tasks 579a7059eb6af87dcc6ef4e2
  Error posting http://localhost:8080/tasks/579a7059eb6af87dcc6ef4e2 (400 Bad Request): {"error":"params must be a JSON array of task params"}
  $ disbatch create-tasks 579a7059eb6af87dcc6ef4e2 '{}'
  Error posting http://localhost:8080/tasks/579a7059eb6af87dcc6ef4e2 (400 Bad Request): {"error":"params must be a JSON array of task params"}
  $ disbatch create-tasks 579a7059eb6af87dcc6ef4e2 '[]'
  Error posting http://localhost:8080/tasks/579a7059eb6af87dcc6ef4e2 (400 Bad Request): {"MongoDB::InsertManyResult":{"acknowledged":1,"inserted":[],"write_concern_errors":[],"write_errors":[]},"error":"Unknown error"}
  $ disbatch create-tasks 579ba809eb6af868d538f631 '[{"fizz":1},{"buzz":2}]'
  Error posting http://localhost:8080/tasks/579ba809eb6af868d538f631 (400 Bad Request): {"error":"queue not found"}
  $ disbatch create-tasks DNE '[{"fizz":1},{"buzz":2}]'
  Error posting http://localhost:8080/tasks/fizzzzzzz (400 Bad Request): {"error":"queue not found"}
create-tasks <queue> --collection <collection> <json_object>

Creates multiple tasks in the specified queue with the given params, based off a filter from another collection.

The json_object must have fields filter and params whose values are Objects.

In the below example, the users collection is queried for all documents matching {migration: "foo"}. These documents are then used to set task params, and the values from the query collection are accessed by prepending document..

  $ disbatch create-tasks 56eade3aeb6af81e0123ed21 --collection users '{"filter":{"migration":"foo"},"params":{"user":"document.username","migration":"document.migration"}}'
  Created 2 tasks in queue 56eade3aeb6af81e0123ed21
  579b72a5eb6af86a8f5220f1
  579b72a5eb6af86a8f5220f2

Error examples:

  $ disbatch --collection DNE create-tasks 579a7059eb6af87dcc6ef4e2 '{"filter":{"migration":"foo"},"params":{"user":"document.username"}}'
  Error posting http://localhost:8080/tasks/test/DNE (400 Bad Request): {"MongoDB::InsertManyResult":{"acknowledged":1,"inserted":[],"write_concern_errors":[],"write_errors":[]},"error":"Unknown error"}
tasks [<json_filter>] [[--limit <limit>] [--skip <skip>] [--fields] [--noterse] [--epoch] [--pretty] | [--count]]

Returns a JSON array of task documents matching the JSON query given. Note that blessed values may be munged to be proper JSON. Limit of 20 documents returned by default.

  $ disbatch tasks '{"queue":"56eade3aeb6af81e0123ed21"}'
  [{"ctime":1469805221.996,"stderr":null,"status":-2,"mtime":1469805221.996,"_id":{"$oid":"579b72a5eb6af86a8f5220f1"},"node":null,"params":{"migration":"foo","user":"ashley"},"queue":{"$oid":"56eade3aeb6af81e0123ed21"},"stdout":null},{"ctime":1469805221.996,"stderr":null,"status":-2,"mtime":1469805221.996,"_id":{"$oid":"579b72a5eb6af86a8f5220f2"},"node":null,"params":{"migration":"foo","user":"matt"},"queue":{"$oid":"56eade3aeb6af81e0123ed21"},"stdout":null}]

The option --limit can be used to change the maxinum number of documents returned. The option --skip can be used to skip that number of documents in returned results. The option --fields can be used to only return the specified fields of tasks.

The option --noterse can be used to disable terse mode (on by default). If enabled, the GridFS id or "[terse mode]" will be returned for stdout and stderr of each document. If disabled, the actual values of stdout and stderr will be returned, which may be a MongoDB::OID object. The option --full will replace any MongoDB::OID values of stdout and stderr with their full content.

The option --epoch will return ctime and mtime as FIXME instead of FIXME.

The option --pretty can be used to have the response pretty-printed.

If the option --count is used, returns a count of the matching task documents instead.

  $ disbatch tasks '{"queue":"56eade3aeb6af81e0123ed21"}' --count
  2 tasks

Error examples:

  $ disbatch tasks '[]'
  Invalid filter is not a JSON object: '[]'
  $ disbatch tasks '{"status":-2}'
  Error getting http://localhost:3002/tasks (400 Bad Request): {"error":"non-indexed params given","indexes":[["id"],["node","status","queue","id"],["queue","status"]],"invalid_params":["status"],"path":"/tasks","title":"Disbatch Tasks Query"}
search [<json_filter>] [--options <options>] [--count | --terse]

DEPRECATED: requires Disbatch::Web::Tasks. use the new tasks command above.

Returns a JSON array of task documents matching the JSON query given. Note that blessed values may be munged to be proper JSON. Limit of 100 documents returned.

  $ disbatch search '{"params.migration":"foo"}'
  [{"ctime":1469805221.996,"stderr":null,"status":-2,"mtime":1469805221.996,"_id":{"$oid":"579b72a5eb6af86a8f5220f1"},"node":null,"params":{"migration":"foo","user":"ashley"},"queue":{"$oid":"56eade3aeb6af81e0123ed21"},"stdout":null},{"ctime":1469805221.996,"stderr":null,"status":-2,"mtime":1469805221.996,"_id":{"$oid":"579b72a5eb6af86a8f5220f2"},"node":null,"params":{"migration":"foo","user":"matt"},"queue":{"$oid":"56eade3aeb6af81e0123ed21"},"stdout":null}]

The option --pretty can be used to have the response pretty-printed.

If the option --count is used, returns a count of the matching task documents instead.

  $ disbatch search '{"params.migration":"foo"}' --count
  2 tasks

The option --options can be used to pass additional options to MongoDB::Collection#find. It's value is a JSON Object. Use --options '{"limit":20}' to return only the first 20 documents (default is 100). This will fail if you try to set it above 100.

The option --noterse can be used to disable terse mode (on by default). If enabled, the GridFS id or "[terse mode]" will be returned for stdout and stderr of each document. If disabled, the full content of stdout and stderr will be returned.

Error examples:

  $ disbatch search '[]'
  Error posting http://localhost:8080/tasks/search (400 Bad Request): {"error":"filter and options must be name/value objects"}
  $ disbatch search '"foo"'
  Invalid filter is not JSON: '"foo"'

SEE ALSO

Disbatch

Disbatch::Web

Disbatch::Roles

Disbatch::Plugin::Demo

task_runner

disbatchd

disbatch-create-users

AUTHORS

Ashley Willis <awillis@synacor.com>

Matt Busigin

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016, 2019 by Ashley Willis.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004