A common agent to execute configured command and serve file read write via HTTP protocol

cd <path to project>
make

cd <path to project>
make rpm

cd <path to project>
make tarball

By defaults, only mysql database driver are built in. You can use make DRIVERS="mysql sqlite postgres" to choose other drivers.

/path/to/servant/scripts/servantctl (start|stop|restart|status|help)

Usage of ./servant:
    -conf value
            config files path
    -confdir value
            config directories path
    -var value
            vars

• -conf

  Config file path. can presents multiple times.

• -confdir

  Config directories path. All config files in it will be loaded. Can presents multiple times.

• -var

  Predefined vars. e.g. -var foo=bar can be referenced as ${_arg.foo}. Can presents multiple times.

See conf/example.xml

Servant config file is in xml, may looks like this;

<?xml version="1.0" encoding="utf-8" ?>
<config>
    <server>
        <listen>:2465</listen>
        <auth enabled="0">
            <maxTimeDelta>300</maxTimeDelta>
        </auth>
        <log>servant.log</log>
    </server>

    <commands id="db1">
        <command id="foo" runas="mysql" lang="bash">
            <code>echo "hello world $(whoami)"</code>
        </command>
        <command id="grep" lang="exec">
            <code>grep hello</code>
        </command>
        <command id="sleep" timeout="5" lang="exec">
            <code> sleep ${t}</code>
        </command>
    </commands>

    <daemon id="daemon1" retries="10" lang="bash">
        <code>sleep 10000</code>
    </daemon>

    <timer id="xx" tick="5" deadline="5" lang="bash">
        <code>
        <![CDATA[
             date >>/tmp/timer.log
        ]]>
        </code>
    </timer>

    <files id="db1">
        <dir id="binlog1">
            <root>/data/mysql0</root>
            <allow>get</allow>
            <allow>head</allow>
            <allow>post</allow>
            <allow>delete</allow>
            <allow>put</allow>
            <pattern>log-bin\.\d+</pattern>
        </dir>
    </files>

    <database id="mysql" driver="mysql" dsn="root:@tcp(127.0.0.1:3306)/test">
        <query id="select_1"><sql> select 1 </sql></query>
    </database>

    <vars id="vars">
        <var id="foo">
            <value>bar</value>
        </var>
        <var id="hello" expand="true">
            <value>${world}</value>
        </var>
    </vars>

    <user id="user1">
        <key>someKey</key>
        <host>192.168.1.0/24</host>
        <files id="db1" />
        <commands id="db1" />
    </user>
</config>

Server level configs.

Address to bind on and listen, can be <ip>:<port> or :<port> e.g. 0.0.0.0:2465, :2465

Authorization config.

• Attribute enabled:

  can be 0 or 1. When authorization disabled, user config has no use.

• Element server/auth/maxTimeDelta:

  Max time delta between servant server and client allowed.

Log file path. If not set, log will be writen to stdout.

Resources group elements can be commands, files, database, vars which defines some resource item elements. Each resource group and resource item elements must has an id attribute. Client can reference a resource by /<resource_type>/<group>/<item>, e.g. /commands/db1/foo. daemon, timer does not has a group, they are defined directly under server element.

Defines a group of commands can be executed, contains some command elements.

• Attribute lang:

  Can be bash, exec.
  As bash, code is executed as bash, supports if, for, pipe etc, but not supports parameter replacement.
  As exec, code implies just a single command and arguments separated by spaces. You can use ${param_name} as a placeholder, and replace it by query parameters. If you want to use an argument contains spaces, you can wrap it by quotes e.g. "hello world", 'hello servant'.

• Attribute runas:

  The system user to execute the command, default is current user. To use runas, servant must be run as root.

• Attribute timeout:

  Limit the command execution time in seconds, default is unlimited.

• Attribute background:

  Whether the command runs in background. Could be true or false. When background == true, Servant will return immediately.

• Element code:

  Code of the command to be executed

• Element lock:

  Mutex. Attributes: name: locks with same name is exclusive. wait: when race for the lock failed, wait until the lock is released or return immediately, default is false. timeout: Max time to wait for the lock, in seconds.

• Element validate:

  Validate params. Attributes: name: param name to validate. Body: Validator regexp.

• Attribute lang:

  Can be bash, exec. see commands/command

• Attribute runas:

  The system user to execute the command. see commands/command

• Attribute retries:

  Retry times when run code failed.

• Attribute live:

  Seconds a daemon runs before failed to reset retry counter. Default is unlimited.

• Element code:

  Code of the command to be executed

• Attribute lang:

  Can be bash, exec. see commands/command

• Attribute runas:

  The system user to execute the command. see commands/command

• Attribute tick:

  Interval in seconds to trigger the timer

• Attribute deadline:

  Seconds of the max duration the timer task can runs.

• Element code:

  Code of the command to be executed

Defines some directories can be accessed.

A directory can be accessed.

• Element root:

  The root of the directory. Access will be limited in it.

• Element allow:

  Methods allows to access the files in the directory. can be get, post, put, delete, head. Which means read, create, update, delete, stat. This element can appearances more than one times.

• Element pattern:

  File name patterns allowed to be access in regular expression. If not defined, all files in the directory can be accessed. This element can appearances more than one times.

• Element validate:

  Validate params. Attributes: name: param name to validate. Body: Validator regexp.

A database resource.

• Attribute driver:

  Database driver, supports mysql, sqlite, postgresql.

• Attribute dsn:

  Data source name, see driver document: mysql, sqlite, postgresql. e.g. (mysql) root:password@tcp(127.0.0.1:3306)/test

Sqls to be executed. Will be executed during a database session.

• Element sql:

  A sql. You can use ${param_name} as a placeholder, and replace it by query parameters. Can appearances multiple times.

• Element validate:

  Validate params. Attributes: name: param name to validate. Body: Validator regexp.

Defines a group of variables.

Variables expand can be used in command, var, file/root. ${param_name} is a request param, ${group.item} is a user define varaible, ${_arg.name} is a command-line argument variable. Variable expand can also defined recursively, like ${group.${item_param}}

A variable

• Attribute expand:

  Whether expands variables in value or not.

• Attribute readonly:

  Whether value can be updated online or not.

• Element value:

  Default variable value.

• Element pattern:

  Regexp pattern the value must matchs.

Defines a user and which resources who can access. Can appearances multiple times.

Authorization key.

Host allowed access from by user. Can appearances multiple times.

• Attribute id:

  id of files can be access. Can appearances multiple times.

• Attribute id:

  id of commands can be access. Can appearances multiple times.

• Attribute id:

  id of database can be access. Can appearances multiple times.

servant uses HTTP protocol. You can use curl http://<host>:<port>/<resource_type>/<group>/<item>[/<sub item>] to access resources., e.g. curl http://127.0.0.1:2465/commands/db1/foo to execute a command foo in db1 group.

only supports GET and POST method.

curl http://127.0.0.1:2465/commands/db1/foo

echo "hello world" | curl -XPOST http://127.0.0.1:2465/commands/db1/grep -d @-

curl http://127.0.0.1:2465/commands/db1/sleep?t=2

curl http://127.0.0.1:2465/files/db1/binlog1/log-bin.000001

curl -H 'Range: bytes=6-10' http://127.0.0.1:2465/files/db1/binlog1/test.txt

echo "hello world!" | curl -XPOST http://127.0.0.1:2465/files/db1/binlog1/test.txt -d @-

echo "hello world!" | curl -XPUT http://127.0.0.1:2465/files/db1/binlog1/test.txt -d @-

curl -XDELETE http://127.0.0.1:2465/files/db1/binlog1/test.txt

curl -I http://127.0.0.1:2465/files/db1/binlog1/test.txt

Outputs are in json format

curl http://127.0.0.1:2465/databases/mysql/select_1

curl http://127.0.0.1:2465/databases/mysql/select_v?v=hello

curl http://127.0.0.1:2465/vars/foo

curl -XPOST http://127.0.0.1:2465/vars/foo -d 'BAR'

servant uses a Authorization head to verify a user access.

The format is Authorization: <username> <timestamp> sha1(<username> + <key> + <timestamp> + <method> + <uri>).

Timestamp is a 32bit UNIX timestamp; method is in uppercase.

e.g.

uri='/commands/db1/foo'
ts=$(date +%s)
user=user1
key=someKey
curl -H "Authorization: ${user} ${ts} $(echo -n "${user}${key}${ts}GET${uri}"|sha1sum|cut -f1 -d' ')"  "http://127.0.0.1:2465${uri}"