From a0b3e1a564b6b8b728a61002d10e2f2f16447bbe Mon Sep 17 00:00:00 2001 From: Jermolene Date: Wed, 17 Oct 2018 21:27:46 +0100 Subject: [PATCH] Docs improvements --- .../tiddlers/system/HelloThere.tid | 9 ++++ .../WidgetMessage_ tm-execute-job.tid | 24 +++++++++ .../tiddlers/nodejs/tiddlywiki.info_Files.tid | 4 +- .../webserver/Using remote commands.tid | 51 +++++++++++++++++++ .../WebServer API_ Post Commands.tid | 27 ++++++++++ 5 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 editions/tw5.com/tiddlers/WidgetMessage_ tm-execute-job.tid create mode 100644 editions/tw5.com/tiddlers/webserver/Using remote commands.tid create mode 100644 editions/tw5.com/tiddlers/webserver/WebServer API_ Post Commands.tid diff --git a/editions/externalpipesdemo/tiddlers/system/HelloThere.tid b/editions/externalpipesdemo/tiddlers/system/HelloThere.tid index b1c6f6a83b..12542a9c7d 100644 --- a/editions/externalpipesdemo/tiddlers/system/HelloThere.tid +++ b/editions/externalpipesdemo/tiddlers/system/HelloThere.tid @@ -24,6 +24,15 @@ Mimic Stats +<$button> +<$action-sendmessage $message="tm-execute-job" 0="--verbose" 1="--fetch" 2="raw-file" 3="http://api.open-notify.org/astros.json" statusTitle="JobStatus"/> +Fetch number of people in space + + +Output: + +{{http://api.open-notify.org/astros.json}} + This demo requires the example task `reverser.js 8081` to be running in a separate command window. <$button> diff --git a/editions/tw5.com/tiddlers/WidgetMessage_ tm-execute-job.tid b/editions/tw5.com/tiddlers/WidgetMessage_ tm-execute-job.tid new file mode 100644 index 0000000000..6b3e433486 --- /dev/null +++ b/editions/tw5.com/tiddlers/WidgetMessage_ tm-execute-job.tid @@ -0,0 +1,24 @@ +caption: tm-server-refresh +created: 20181017140932589 +modified: 20181017171440568 +tags: Messages +title: WidgetMessage: tm-execute-job +type: text/vnd.tiddlywiki + +<<.from-version "5.1.18">> The "execute job" message triggers the execution of [[remote commands|Using remote commands]]. It uses the message parameters as follows: + +|!Name |!Description | +|$param |Not used | +|commands |Command string to be executed | +|0...n |Command tokens to be executed | +|statusTitle |Optional title of tiddler in which to store status updates as the commands are executed | + +Note that the command string to be executed can either be passed as a single string, or as a sequence of tokens: + +* A single string: +*> `<$action-sendmessage $message="tm-execute-job" commands="--version"/>` +* Separate command tokens with numeric indices: +*> `<$action-sendmessage $message="tm-execute-job" 0="--version" 1="--version"/>` +** Note that the numeric indices must be non-negative integers with no leading zeros + +The "execute job" message is handled by the TiddlyWiki core SyncMechanism which invokes the current [[SyncAdaptorModule|SyncAdaptorModules]] (typically the ''tiddlywiki/tiddlywebadaptor'' plugin). diff --git a/editions/tw5.com/tiddlers/nodejs/tiddlywiki.info_Files.tid b/editions/tw5.com/tiddlers/nodejs/tiddlywiki.info_Files.tid index 58dfaed685..c922e4d16f 100644 --- a/editions/tw5.com/tiddlers/nodejs/tiddlywiki.info_Files.tid +++ b/editions/tw5.com/tiddlers/nodejs/tiddlywiki.info_Files.tid @@ -1,5 +1,5 @@ created: 20161015114042793 -modified: 20161015121622327 +modified: 20181017171429110 tags: TiddlyWikiFolders title: tiddlywiki.info Files type: text/vnd.tiddlywiki @@ -32,6 +32,8 @@ Configuration options include: * ''retain-original-tiddler-path'' - If true, the server will generate a tiddler [[$:/config/OriginalTiddlerPaths]] containing the original file paths of each tiddler in the wiki +* ''allow-remote-commands'' - <<.from-version "5.1.18">> if true, [[remote commands|Using remote commands]] will be permitted for all authorized users + !!! Example For example: diff --git a/editions/tw5.com/tiddlers/webserver/Using remote commands.tid b/editions/tw5.com/tiddlers/webserver/Using remote commands.tid new file mode 100644 index 0000000000..4e69d5cb55 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/Using remote commands.tid @@ -0,0 +1,51 @@ +created: 20181014180409461 +modified: 20181017202202358 +tags: [[WebServer Guides]] +title: Using remote commands +type: text/vnd.tiddlywiki + +The remote commands mechanism allows browsers connected to TiddlyWiki's WebServer to initiate the execution of [[commands|Commands]] on the server. + +In the browser it is initiated by the [[tm-execute-job|WidgetMessage: tm-execute-job]] message: + +``` +<$action-sendmessage $message="tm-execute-job" commands="--version" statusTitle="JobStatus"/> +``` + +On the server, it is implemented by the [[WebServer API: Post Commands]]. + +<<.warning """To avoid potential security risks the remote commands mechanism is disabled by default. Please carefully read the security notes below before enabling it. """>> + +!! Security Considerations for Remote Commands + +Enabling the remote command mechanism allows any authenticated user connecting via the [[WebServer API]] to execute arbitrary [[commands|Commands]] on the server. TiddlyWiki's built-in commands are generally unfettered: for example, they include the ability to write to any file in the file system. This risks giving an adversary complete control of the system. + +The risks can be mitigated in several ways: + +* Restrict listening to [[host|WebServer Parameter: host]] 127.0.0.1 so that only processes running on the same machine can connect to the server +* Require [[authentication|WebServer Authentication]] +* Enable [[HTTPS|Using HTTPS]] + +!! Enabling Remote Commands + +Remote command execution is enabled by setting to 'true' the property `allow-remote-commands` of the `config` section of [[tiddlywiki.info Files]]. For example: + +``` +"config": { + "allow-remote-commands": true +}, +``` + +!! Using Remote Commands + +Remote commands are invoked from the browser using the [[tm-execute-job|WidgetMessage: tm-execute-job]] message. + +This example fetches JSON data from `http://api.open-notify.org/astros.json` and places it in a tiddler called [[http://api.open-notify.org/astros.json]]. + +``` + +<$button> +<$action-sendmessage $message="tm-execute-job" 0="--verbose" 1="--fetch" 2="raw-file" 3="http://api.open-notify.org/astros.json" statusTitle="JobStatus"/> +Fetch number of people in space + +``` diff --git a/editions/tw5.com/tiddlers/webserver/WebServer API_ Post Commands.tid b/editions/tw5.com/tiddlers/webserver/WebServer API_ Post Commands.tid new file mode 100644 index 0000000000..6ae32f4d37 --- /dev/null +++ b/editions/tw5.com/tiddlers/webserver/WebServer API_ Post Commands.tid @@ -0,0 +1,27 @@ +created: 20181014175732191 +modified: 20181014180331643 +tags: [[WebServer API]] +title: WebServer API: Post Commands +type: text/vnd.tiddlywiki + +Posts a string of command tokens for execution by the server. + +Note that remote command execution is only permitted if explicitly enabled -- see [[Using remote commands]]. + +``` +POST /commands/ +``` + +The body should be an object in JSON format with the following properties: + +* ''commands'' - an array of command token strings +* ''statusTitle'' - the title of a tiddler to receive a status string resulting from executing the commands + +Parameters: + +* none + +Response: + +* 204 No Content +* 404 Not Found