Scripting and Web API
Table of contents
Command scripting
Batch mode and interactive mode
Some examples
Command output
Web API
Command scripting
From version 0.8.4 onwards, MinimServer and MinimWatch include a scripting client application. You can use this application to control and configure MinimServer by running a single MinimServer console command or a scripted list of console commands (a command script). The available commands are listed in the Controlling MinimServer using console commands section.
The scripting client application must be run in a command prompt window (Windows) or a terminal window (Mac or Linux).
The command to run the scripting client application is named mscript and its location
depends on which platform you are using, as follows:
-
On Windows, the
mscriptcommand is located in thebinfolder underneath the folder where you installed MinimServer or MinimWatch (normally C:\Program Files\MinimServer\bin\mscript.cmd or C:\Program Files\MinimWatch\bin\mscript.cmd). -
On Mac, the
mscriptcommand is located in theContentsfolder within the MinimServer or MinimWatch application (normally /Applications/MinimServer.app/Contents/mscript or /Applications/MinimWatch.app/Contents/mscript). -
On Linux, the
mscriptcommand is located in theminimserver/binorminimwatch/bindirectory underneath the directory where you installed MinimServer or MinimWatch (<minim-home>/minimserver/bin/mscript or <minim-home>/minimwatch/bin/mscript). - On a Synology NAS, the full path is /var/packages/MinimServer/target/bin/mscript.
-
On a QNAP NAS, the full path depends on what model of NAS you have and the volume
you chose when installing the MinimServer package. The following shell expression
returns the correct path:
$(/sbin/getcfg MinimServer Install_Path -f /etc/config/qpkg.conf)/bin/mscript - On an ASUSTOR NAS, the full path is /usr/local/AppCentral/minimserver/bin/mscript.
- On a NETGEAR ReadyNAS, the full path is /etc/frontview/addons/bin/MINIMSERVER/bin/mscript.
The syntax of the mscript command is as follows:
mscript [ options ] [ script-file ]
where options is any combination of the following:
-i
| use interactive mode |
-a address
| host and port address of the server |
-t timeout
| number of seconds (default 5) to wait for server response |
-c command
| single command to run |
-d
| enable debug output |
--help
| show syntax summary |
If you specify the script-file argument, mscript reads the command script from a file, which must be plain text.
if you don't specify the script-file argument, mscript reads the command script from the standard input stream,
which can either be connected to an interactive console or redirected to read input from a pipe or a file.
If the -c option is specified, the value of this option is used
as a single command to run instead of running a command script.
If the mscript command is invoked with
no options or arguments and the standard input stream isn't redirected, mscript displays a syntax summary.
If you want to read commands from an interactive console with defaults for all options,
you can use the command mscript -i to do this.
The host and port address of the server can be an IP address (for example, 192.168.1.20)
or an IP address and port number (for example, 192.168.1.20:9792).
If this address isn't specified, the mscript command attempts to
locate a MinimServer instance running on the local machine and
run the command script on this instance.
A command script can contain any number of commands. Lines starting with '#' are ignored.
If the script contains multiple commands, the commands must be separated by newline characters.
Batch mode and interactive mode
The mscript command can run in either batch mode or interactive mode.
The -i option is used to specify interactive mode. If this option isn't specified,
the default setting is interactive mode if mscript is reading commands
from an interactive console and batch mode in all other cases.
In batch mode, mscript sends a list of commands (a command script) to MinimServer and
MinimServer runs these commands in sequential order until the end of the script is reached
or a command returns an error.
If a command returns an error, no more commands are run.
The output from the last command to be run
(either sucessfully or with an error) is written by mscript to the standard output stream
in the format described in the Command output section below.
Batch mode is useful for running a fixed sequence of commands.
In interactive mode, mscript reads commands one at a time
and sends them to MinimServer for immediate processing. When a command completes (successfully or
with an error), mscript writes the command output (see the Command output
section below) to the standard output stream before reading the next command.
Command processing ends when mscript reads a null command (empty string)
or reaches the end of the command script.
Interactive mode is useful if mscript is reading commands from an
interactive console or being controlled programmatically
by another application.
The Linux download packages for MinimServer and MinimWatch include a demonstration shell script
scriptdemo.sh that shows how the interactive mode of mscript can
enable an application to control MinimServer by issuing commands and using
programmatic logic to read command output and determine what action to take next.
Some examples
Here are some examples of how the mscript command can be used:
-
mscript myscript.txt -
reads a command script from a file named
myscript.txtand runs the commands in batch mode on a MinimServer instance running on the local machine -
mscript -i - reads commands from an interactive console and runs the commands in interactive mode on a MinimServer instance running on the local machine
-
mscript -c rescan -
runs the single command
rescan -
myprog | mscript -
runs the program
myprogto output a command script that is piped to themscriptcommand and run in batch mode by a MinimServer instance on the local machine -
myprog | mscript -i -
runs the program
myprogto output a command script that is piped to themscriptcommand and run in interactive mode by a MinimServer instance on the local machine -
mscript <infile >outfile -
reads the command script from the file
infile, runs the command script in batch mode and writes the command output to the fileoutfile -
mscript -a 192.168.1.20 myscript.txt -
reads a command script from a file named
myscript.txtand runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20 -
mscript -a 192.168.1.20:9792 myscript -
reads a command script from a file named
myscriptand runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20 and HTTP port number 9792
Command output
mscript writes the output from running the command script (in batch mode)
or each individual command (in interactive mode) to the standard output stream.
This output is in three parts:
-
The last command that was run, preceded by the prefix
+* - The output from the command
-
A status line of the form
+:status=n, where n is the completion status (see below)
For example, the command about might produce the following output:
+*about
MinimServer0.8.4, Copyright (c) 2012-2017 Simon Nash. All rights reserved.
+:status=0
and the command install foo might
produce the following output:
+*installfoo
Downloadresource not found: foo.jmpkg
+:status=1
For successful completion of a command or command script, the completion status is 0.
If the command or command script has been run by MinimServer and returned a error, the completion status is 1.
If the command or command script couldn't be sent to MinimServer, mscript writes an error message
to the standard error stream and the completion status
is 2 if the server address wasn't found or 3 for any other error.
The following commands are treated specially:
restart
| restarts the server and waits for the server to restart. If any commands follow this command in the script, the next command is run when the server has restarted. |
rescan
|
performs a server rescan (including a server restart).
If mscript is running in batch mode and there are any commands following this command
in the script, the next command is run when the rescan has completed.
If mscript is running in interactive mode and there are any commands following this command
in the script, the next command is run when the server has restarted
and is beginning the rescan.
|
relaunch
| relaunches the server and waits for the server to relaunch. If any commands follow this command in the script, the next command is run when the server has relaunched. |
exit
| terminates the server. If any commands follow this command in the script, an error is returned for the next command. |
Web API
The MinimServer web API provices a mechanism for applications to send commands programmatically to
MinimServer. An example of an application that does this is the mscript
scripting client application (see the Command scripting section).
http://address:port/where address is the IP address of the machine runing MinimServer and port is the HTTP server port that MinimServer is using on this machine (see the HTTP server port section). The content type for the request must be
text/plain and the content data must be a
command script containing console commands listed in the
Controlling MinimServer using console commands
section.
The command script can contain any number of commands. Lines starting with '#' are ignored.
If the script contains multiple commands, the commands must be separated by newline characters.
MinimServer runs each command in the script in sequence until all commands have completed successfully or any of the commands returns an error. If a command returns an error, no more commands are run.
The HTTP POST response content data has a content type of text/plain and
contains the last command that was run and the output from this command, preceded
by the prefix +*.
For example, the command about might
return the following:
+*about
MinimServer0.8.4, Copyright (c) 2012-2017 Simon Nash. All rights reserved.
and the command install foo might
return the following:
+*installfoo
Downloadresource not found: foo.jmpkg
If all commands complete successfully, the HTTP POST response status code is 200. If an error occurs while running a command, the HTTP POST response status code is 400 or greater.
The following commands are treated specially:
restart
| restarts the server and waits for the server to restart. The HTTP 200 OK response is sent when the server has restarted. If any commands follow this command in the list, the next command is run when the server has restarted. |
rescan
| performs a server rescan (including a server restart). The HTTP 200 OK response is sent when the server has restarted and is beginning the rescan. If any commands follow this command in the list, the next command is run when the rescan has completed. |
relaunch
| relaunches the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the next command. |
exit
| terminates the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the next command. |