Documentation and help portal

regiboxd Specification

Introduction

The regify regibox Manager is a file desktop collaboration tool. This document describes the usage of its background daemon or service counter part. The main program is herein referred to as regiboxd, which stands for regibox daemon. On Microsoft Windows this is also known as a service and it is implemented that way for Windows, but nevertheless called regiboxd. regiboxd is available for 64 bit Windows and Linux amd64/x86_64 architectures. All mentioned executables here end with .exe on Windows, but the extension is left out here for brevity as it is also not present on the Linux version.

regiboxd ships with a control application called regiboxctl. regiboxctl can be used as a convenience tool to control a given regiboxd instance. Instances are created with their individual configuration directories, which are unique to every regiboxd instance and do not contain the regibox file root folder of a given instance. That root folder must also be unique, but is recommended to reside outside of configuration directory.

The daemon

regiboxd is the main process of a given instance. It is the process synchronizing files and observing for file changes. One instance is able to synchronize and handle multiple regiboxes (like regibox Manager for Desktop does). You are also able to run multiple instances of regiboxd (as services on Windows and daemons on Linux). But please note that multiple instances are only needed if you plan to run the instances with different regify accounts. As long as you are using one regify account only, one regiboxd Service/Daemon is sufficient.

Windows / Linux

On Windows it is generally installed and then run as a service. Service related items for Windows integrator will be covered here. Generally running regiboxd from the command line will respond with the help screen complaining about a missing configuration directory. This help will look something like this on Windows, but it’s best to run regiboxd without any parameters or with the -h switch to see an up to date version for your given platform.

C:\Users\regify>regiboxd
Please specify a valid config directory with -c
regiboxd.exe - regibox Manager Version 2.1.0-7078 (c) 2015-2021 regify GmbH

This is a headless build designed to run as a daemon or service.

Usage:
regiboxd.exe <OPTIONS>

GENERAL OPTIONS:
-c Configuration directory for this regibox instance.
-D Start in diagnostics mode. Send {"op":"diagnostics"} to terminate.
-l Specifies log file to log debugging information to.
   The following tokens may be used and are replaced:
     +D The start date formatted like yyyy-mm-dd (2021-04-21)
     +T The start time formatted like HH-MM-SS (15-29-03)
     +P The process id (2902)
     ++ A plus (+)
-r Initial path to box root folder. Ignored when ini file entry is present.
-v Increases debug logging level to verbose. Ignored without -l.
-h This output.

SERVICE OPTIONS:
-i Specify a unique service name under which to install a regibox service.
   Requires -c to be set to a unique configuration.
   If -l and -v are set, they will configure debug logging for the
   installed service. This is generally not recommended unless there are
   startup issues that can't be reproduced from the command line.
-d Description label for the service to be installed. Ignored without -i.
-L List currently installed regibox services and their stati.
-m Machine parsable output, no headers and includes service name.
-u Specify the service name to deinstall.

It is recommended to cover the string parameters using quotation marks.
It is absolutely needed in case of spaces or other special characters.

The -c switch is mandatory for all calls except -L, -u and -h. The -r switch is required when there is not yet a box root folder specified in the configuration. This is usually the case the first time the instance is installed. It takes a path to the folder under which all regiboxes will reside. This may be a relative path as it will be resolved to a full path.

You must not ever point this to a folder which is already used by another regibox instance (regiboxd or regibox manager). Only one regibox instance is allowed to monitor a given boxRoot at any time.

The -r switch is silently ignored when this value is already set in the configuration.

The remaining options pretty much describe themselves.

In order to register -i or unregister -u an instance, the shell must be run as Administrator. All other variants can normally be run as a regular user. As it says, it is recommended to properly quote things on DOS or properly escape blanks and such on other shells.

Linux

Generally running regiboxd from the command line will respond with the help screen complaining about a missing configuration directory. Have a look at the help output there.

On Linux the software starts as a daemon by default, unless you specify the -f switch to keep it in the foreground, but due to the multitude of startup systems Sys-5, upstart, systemd just to name a few, that part is left to the developer integrating regiboxd into a Linux landscape. Because of this, the SERVICE OPTIONS are not available on Linux.

Please make sure that regiboxd is automatically started on your system during boot!

Installing an instance

To be able to run as a Windows service, a regiboxd instance must first be installed on the system. Open a shell prompt as Administrator. We use the DOS prompt as an example, not because it is recommended, but because it’s ubiquitous. Tools such as Power shell are probably better at this. In the following example we assume a folder C:\example and regiboxd is on the program PATH.

C:\example>regiboxd -c boxconfig -r boxroot -i test1 -d "A test regiboxd instance"
Service test1 has been successfully installed.

The -d switch is optional. The folder boxconfig and the necessary sub folders will be created. Instead of boxconfig it could have also been boxconfig\subfolder. It is acceptable to specify relative paths at this point because they will be made full by prepending the current working directory. If we now get a service listing we will see our newly created instance.

C:\example>regiboxd -L
Currently installed regiboxd service instances. Name, Command line, ACTIVE(pid) means running
test1   "C:\regiboxd.exe" -I "regiboxd_test1" -c "C:\example\boxconfig\"     ACTIVE(1828)

Here we see that our service test1 is running with process id 1828 and configuration directory C:\example\boxconfig\, which is the full path to what we specified. The -I argument is internal and only used by the service manager. We also see that our actual service name is prefixed with regiboxd_. This is needed so we can find our instances with -L. If there are other non regiboxd services that start with regiboxd_, they will be listed as well. Administrating them with regiboxd is obviously not recommended. Finally to uninstall an instance again we do the following:

C:\example>regiboxd -u test1
Service test1 has been successfully deleted.

Sometimes a service lingers after deinstallation. That has been observed to happen when the service viewer or registry editor was open during the de-installation. A Windows restart usually cleans that up.

You must not ever point your configuration to a directory which is already used by another regibox instance (regiboxd or regibox manager). It must be a unique directory for this configuration.

Controlling regiboxd

Manual control using filesystem

Communication with a regiboxd instance is generally done through the file system. The reason this approach was chosen is its flexibility and cross platform compatibility. To initiate a request, a file called request.tmp should be written into the req folder of your instances configuration folder. Then it should be renamed request. The reason we write a temp file and then rename it, is to make the operation atomic, so that regiboxd doesn’t try to read the file before we’re done writing it.

So the path for our above instance would have been
C:\example\boxconfig\req\request.tmp
followed by a rename to
C:\example\boxconfig\req\request

This file should contain UTF-8 encoded JSON as described in the chapter below. In the odd circumstance where the regiboxd instance is not running it will pick up the request when it starts. It is generally assumed to be running. It will respond by also writing a UTF-8 encoded JSON file into its res folder. It also writes response.tmp and then renames it to response, so once that file is present it can safely be read and should be deleted thereafter. In general it’s a good idea to check for and delete this file before launching a request.

In our example the full response paths would have been
C:\example\boxconfig\res\response.tmp
and
C:\example\boxconfig\res\response

This file only contains results of synchronous calls. Asynchronous calls like getPastVersion may error out at a later point. These errors are generally logged in the event log. By default the events are written to syslog on Unix platforms and the event log on Windows. They may also be written to a separate file if requested, see the eventLogPath setting in newConfig.

Request Ids

As of version 2.1 regiboxd accepts request specific ids to go along with individual requests. These ids are encoded in the file name and allow matching a response to a request. They may consist of any string but should be kept conservative due to file system restrictions.

The above example with request id could look like this
C:\example\boxconfig\req\request.1234.tmp
followed by a rename to
C:\example\boxconfig\req\request.1234

It is important to note that the temporary file name must end with .tmp and it must start with request. to be accepted as a request. Everything else is as above.

This id is then also to be found in the response file names so that they end up looking like this.
C:\example\boxconfig\res\response.1234.tmp
and
C:\example\boxconfig\res\response.1234

Control using command line tool regiboxctl

To make things more easy we also ship a command line tool called regiboxctl, which handles these details and provides a synchronous caller API. It also documents itself when called without parameters. Like regiboxd it will complain about a missing configuration directory unless called with the -h switch.

C:\example>regiboxctl
Please specify a config directory path

regiboxctl.exe - version 2.1.0-7078 (c) 2018-2021 regify GmbH

Usage:
  regiboxctl -c configDir -j '{"op" : "value"}' [-l test.log]

  OPTIONS:
    -c Config directory. Same as the -c option of the regibox process.
    -h This output.
    -j JSON to post for normal shells. '{"op":"val"}'
    -J JSON to post for the broken DOS shell. "{'op':'val'}"
       All single quotes will be replaced by double quotes.
    -l Optional debug log file path.
       The following tokens may be used and are replaced:
         +D The start date formatted like yyyy-mm-dd (2021-04-21)
         +T The start time formatted like HH-MM-SS (15-29-03)
         +P The process id (2902)
         ++ A plus (+)
    -p Prettified JSON output.
    -q Tell the instance to exit.
    -t Optional time to wait for an answer, defaults to 5 seconds.

regiboxctl allows the caller to specify the JSON request on the command line and returns the response on the console. It is necessary to specify the configuration directory -c, so it knows which instance to communicate with. It will handle all the details of writing the request file and reading the response, as well as any necessary clean up of those.

General Notes

The examples in this document are done using regiboxctl on a bash shell. If you use a DOS shell you need to use the -J JSON notation. In most cases the answers are of the following forms.
This is a typical call and some error message:

Linux bash syntax

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"nonsense"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "Unknown operation [nonsense]",
  "ec"    : 77
}
  • status indicates the outcome of the call

  • desc is a textual sometimes localized other times English description of what happened

  • ec is a regify error code.

  • eMsg is a generic description of the error code in ec and may contain occasional unresolved tokens like <VAL1>.

Windows shell syntax

Because the Windows DOS shell and the Powershell struggle with single and double quotes, regiboxd accepts JSON with single quotes if you use uppercase -J switch. This way you can cover the JSON string in double quotes in the DOS shell as shown in this example:

C:\example>regiboxctl.exe -c test1\conf\ -p -J "{'op':'nonsense'}"
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "Unknown operation [nonsense]",
  "ec"    : 77
}
The drawback of the -J switch is that you cannot use single quotes in your JSON parameters at all!

Examples

Below are steps to accomplish certain tasks.

Empty Recovery Folder of all Boxes

First get the uids of all boxes.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getBoxInfo","fields":["uid"]}'
{
  "status": "OK",
  "boxes": [
    {
      "uid": "jbyt1xpuqf3mu5hauau85ferzr5jytpt"
    },
    {
      "uid": "z6pryo8n5fmyiydb1u9ooaihqener547"
    },
    {
      "uid": "3xogaxj3pctns7jig449gwnysx5pypgo"
    }
  ]
}

Now run emptyRecovery for each one.

$ ./regiboxctl -c test1/conf/ -j '{"op":"emptyRecovery", "uid":"jbyt1xpuqf3mu5hauau85ferzr5jytpt"}'
{"status": "OK"}

Delete past versions of a set of files

First get the files to delete.

  • Specifying the boxPath which must not have a trailing slash.

  • Set recursive to 1.

  • Set filter to Uptodate (32) as the file needs to be local on and up to date. This also filters out folder.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getFileList","boxPath":"box1","recursive":1,"filter":32}'
{
  "files": [
    {
      "BoxName": "box1",
      "BoxPath": "box1/dir1/4kiqfra649",
      "BoxUid": "besg9jijgjfbd8mh9cimg3fdygy4q5gg",
      "Executable": 0,
      "FileId": 28172,
      "FileName": "4kiqfra649",
      "FilePart": "dir1/4kiqfra649",
      "ModDate": "2021-10-08 14:53:06",
      "Size": 105102,
      "Status": 32,
      "UtcModDate": "2021-10-08 12:53:06",
      "VersionId": 26840,
      "VersionTime": 1633697769762860
    },
    {
      "BoxName": "box1",
      "BoxPath": "box1/mdtorq71nwhg4wr",
      "BoxUid": "besg9jijgjfbd8mh9cimg3fdygy4q5gg",
      "Executable": 0,
      "FileId": 10228,
      "FileName": "mdtorq71nwhg4wr",
      "FilePart": "mdtorq71nwhg4wr",
      "ModDate": "2021-11-05 15:52:37",
      "Size": 42446,
      "Status": 32,
      "UtcModDate": "2021-11-05 14:52:37",
      "VersionId": 42937,
      "VersionTime": 1636124262605969
    },
    {
      "BoxName": "box1",
      "BoxPath": "box1/xagiz",
      "BoxUid": "besg9jijgjfbd8mh9cimg3fdygy4q5gg",
      "Executable": 0,
      "FileId": 5153,
      "FileName": "xagiz",
      "FilePart": "xagiz",
      "ModDate": "2021-10-12 15:10:04",
      "Size": 0,
      "Status": 32,
      "UtcModDate": "2021-10-12 13:10:04",
      "VersionId": 32443,
      "VersionTime": 1634044210054324
    }
  ],
  "status": "OK"
}

Now call zapPast on each that is to have its versions removed. You will need BoxUid and FilePart to do this, so for the first entry run

$ ./regiboxctl -c test1/conf/ -j '{"op":"zapPast", "uid":"besg9jijgjfbd8mh9cimg3fdygy4q5gg","filePart":"dir1/4kiqfra649"}'
{"status": "OK"}

Migrate a regiboxd Instance

At times it may become necessary to move a regiboxd installation to another location. This may be another folder on the same machine, or onto another machine altogether. Below we will describe the steps needed for either undertaking. Please be aware of the following aspects.

It is acceptable to use a newer version of regiboxd at the new location, as it will automatically migrate the settings.
It is not ok to use an older version, as it will most likely be incompatible with the new instance settings.

Migrate to another folder

This implies moving the configuration folder and/or the box root folder to a new location on the same machine.

  • The first thing to be done is to shut down the running instance using the adequate means for your platform.

  • The next step is to copy the configuration folder to its new location. Use whatever means you need to do that.

  • Make sure the new configuration folder location is writable and ideally owned by the user running the regiboxd instance.

  • The next step is to move the box root folder to its new location, again using whatever means you have.

  • Make sure the new box root folder location is writable and ideally owned by the user running the regiboxd instance.

  • If the box root folder has changed edit configuration folder/lib/regiboxd.ini or configuration folder/regiboxd.ini for versions before 2.0, and adjust the boxRoot setting to reflect the new location.

  • Now start the regiboxd instance in the new location using the adequate means for your platform.

After that you may use the new instance as you choose.

Migrate to another computer

Migrating a regiboxd instance to another computer with a potentially different user and paths, works the same way as Migrate to another folder with extra steps afterwards.

  • Follow the steps outlined in Migrate to another folder

  • Since this instance is now on a different machine, all credentials in the .ini file need to be reset, because they are currently encrypted to the old machine. To do that you need to call setConfig for the following settings as you are using them:

    • regifyPass - Your regify account pasword. This is mandatory.

    • proxyPass - Optional if you need to authenticate to use a proxy.

    • smtpPass - Optional if you need to authenticate to use SMTP.

Here is a sample call for the regifyPass setting. Be sure to adapt the -c parameter and mysecretpassword to match your settings.

$ ./regiboxctl -c test1/conf/ -j '{"op":"setConfig", "setting":"regifyPass", "value":"mysecretpassword"}'
{"status": "OK"}

After that you may use the new instance as you choose.

API Reference

As mentioned above, regiboxd is controlled by file request containing JSON and answers the same way. This chapter covers what requests are supported. It is organized by documenting all available operations alphabetically. By operations we mean the value associated with the op parameter.

acceptInvite

This function provides a means of accepting invitations and deciding how to handle them.

Key Example value Type Description

op

acceptInvite

string

Accept invitation stored in data.

name

mybox

string

Optional name under which to store this box. Without it the default name in the invitation will be used.

localOn

1

integer

Whether files in this box will be local on by default (1) or not (0). Optional, defaults to 1.

invitePath

/path/to/invite.rbgx

string

File path to the invitation to accept.

data

Type=regibox\nRecip…​

string

Alternative to invitePath. The data of the actual regibox invitation. Ignored when invitePath is set.

A successful sample call looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"acceptInvite","localOn":1,"data": "Type=regibox\nRecipient=\example@regify.com\nSender=...AccessCode=AE21E5F6419FE78910B89A23EC83AFA8\n"}'
{
  "status": "OK"
}

The success message here pertains to the fact that the transaction was found and opened. It says nothing about the validity of the invitation itself, for example the box may have been deleted already. In such a case there will be an event logged. If an invitation is indeed invalid, the response will be as follows:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"acceptInvite","localOn":1,"data": "Type=regibox\nRecipient=\example@regify.com\nSender=...AccessCode=AE21E5F6419FE78910B89A23EC83AFA8\n"}'
{
  "status": "ERROR",
  "eMsg"  : "Sorry, but this transaction can not be opened.",
  "desc"  : "install failed",
  "ec"    : 20
}

The exception is local validations such as you already have this box. That looks like this using invitePath instead of data this time:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"acceptInvite","localOn":1, "invitePath":"regibox_invite.rgbx"}'
{
  "status": "ERROR",
  "eMsg"  : "There's already a box by that name",
  "desc"  : "You already are a member of this regibox under the name \"box1\".",
  "ec"    : 301
}

deleteBox

This function can be called to delete a regibox if you are the owner, or to just unfollow it if you are not. If you are the owner all other users will no longer be able to follow the regibox because it will be deleted from the server. Unfollowing has no effect on other users.

Key Example value Type Description

op

deleteBox

string

Permanently delete or unfollow a regibox.

uid

3xo…​

string

The uid of the box to remove.

keepLocal

0

integer

Optional whether to keep the boxes files in the filesystem. Default is 0.

Here’s a sample call:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"deleteBox", "uid":"4mudnc44a89q7k5g76379mxnz1tykibt"}'
{
  "status": "OK"
}

Nothing to it. A second try:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"deleteBox", "uid":"4mudnc44a89q7k5g76379mxnz1tykibt"}'
{
  "status": "ERROR",
  "eMsg"  : "The regibox could not be found.",
  "desc"  : "failed unsubscribing box uid:d8zcmiringpbf7s5jrad78ctsghtxpqu",
  "ec"    : 48
}

Simply says No.

diagnostics

Sometimes it is necessary to generate debugging information, because something isn’t working as expect or there’s maybe even a bug in regiboxd. In that case the usual procedure is to turn on diagnostics, reproduce the issue and then turn it off again to inspect the data for hints. In regibox Manager this is usually either done by pressing Ctrl+Alt+D twice or starting regibox or regiboxd with the -D flag to catch issues that happen during startup.

Key Example value Type Description

op

diagnostics

string

Start or stop diagnostics mode.

destZipPath

/path/to/diag.zip

string

Optional, absolute path where to write the resulting zip file to. This is ignored when diagnostics are started. Else it will reside at <configDir>/tmp/regiboxd-diagnostics.zip

Again the example call shows the behavior :

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"diagnostics"}'
{
  "status": "OK",
  "desc"  : "diagnostics started"
}

And to stop we issue the same:

$ ./regiboxctl -c test1/conf/ -j '{"op":"diagnostics"}'
{
  "status": "OK",
  "desc"  : "Diagnostics written to /home/user/test1/conf/lib/tmp/regibox-diagnostics.zip"
}

It returns the full path in description. When specifying the path as a relative path it will be based off of the working path of the regiboxd executable not the caller, so full paths are generally recommended.

$ ./regiboxctl -c test1/conf/ -j '{"op":"diagnostics", "destZipPath":"test-diagnostics.zip"}'
{
  "status": "OK",
  "desc"  : "Diagnostics written to test-diagnostics.zip"
}

Then the diagnostics may be examined or sent to support as appropriate. Specifying a non-writable location will result in the following:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"diagnostics", "destZipPath":"/test-diagnostics.zip"}'
{
  "status": "ERROR",
  "desc"  : "Failed writing to destZipPath. Diagnostics written to /home/user/test1/conf/lib/tmp/regibox-diagnostics.zip"
}

In this case they can just be retrieved from their original location.

emptyRecovery

This function empties the recovery bin of a given regibox. As is customary, this action is irreversible.

Key Example value Type Description

op

emptyRecovery

string

Permanently delete all files in the recovery bin of a regibox.

uid

3xo…​

string

The uid of the box of which to empty the recovery bin.

This call has the usual validation and return "OK" regardless of whether actual files were deleted or the recovery bin was empty in the first place:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"emptyRecovery", "uid":"srp79f915967u3doyd8o7orfikjyn5d8"}'
{
  "status": "OK"
}

getActivities

This function retrieves activities that match the specified criteria.

Key Example value Type Description

op

getActivities

string

Get listing of activities.

uid

zqdkecs…​

string

The uid of which to get activities from.

actor

user@example.com

string

Activities that were triggered by actor.

subject

example.txt

string

Affected file or user of activity.

minMicroTime

1535628778303546

integer

Earliest time the activity occurred. Format is microseconds since 1-1-1970.

activityType

1

integer

An optional ORed together value of Activity Types to filter.

limit

100

integer

The maximum number of activities to retrieve.

Activity Types

The activityType field is defined as follows:

// FileDeleted, (1) The file has been deleted.
FileDeleted  = 0x001
// FileName, (2) The file name has been changed.
FileName  = 0x002
// FilePerms, (4) The file permissions (executable for posix only) have been changed.
FilePerms  = 0x004
// FilePurged, (8) The file has been permanently deleted from the server.
FilePurged  = 0x008
// UserRole, (16) The user permissions have been changed.
UserRole  = 0x010
// UserName, (32) The user name has been changed.
UserName  = 0x020
// UserNotes, (64) The user notes have been changed.
UserNotes  = 0x040
// UserRevoke, (256) The user account has been revoked.
UserRevoke  = 0x100
// UserActive, (1024) The user account has been activated.
UserActive  = 0x400
// UserMeta, (2048) The user meta data was changed.
UserMeta  = 0x800
// NewBox, (16777216) The box has been created.
NewBox  = 0x01000000
// NewUser, (33554432) A new user has been invited.
NewUser  = 0x02000000
// NewFile, (67108864) A new file has been created.
NewFile  = 0x04000000
// NewVersion, (134217728) A new version of a file has been created.
NewVersion  = 0x08000000
// SkipOwn, (268435456) Skip events that were created locally.
SkipOwn  = 0x10000000

The response has the following fields

Key Example value Type Description

ActivityType

16777216

integer

The current Activity Type.

Actor

string

The person that initiated the activity.

BoxName

box1

string

The box to which the activity pertains to.

Detail

a test box

string

An activities detail. For activities that made changes this contains the original value.

Detail2

a new value

string

For activities that made changes this contains the new value. Blank for others.

MicroTime

1642581228973888

integer

Time stamp of when this activity was recorded by the provider in µ second resolution.

Subject

file.txt

string

The same as SubjectLong but file names have their path removed leaving only their basename.

SubjectLong

dir/file.txt

string

The subject this activity pertains to. File name for file types, user name for user types, user email for UserActive and box name for NewBox.

SubjectType

33562624

integer

Type information pertaining to the activities subject or 0. This will for file types be the File Perms and for user types the User Roles.

File Perms

The following file flags indicate permissions and other file related aspects.

// PermDeleted, (8388608) This file has been deleted
PermDeleted = 0x0800000
// PermFolder, (16384) This is a folder
PermFolder = 0x0004000
// PermFile, (8192 or 33562624) This is a file
PermFile = 0x0002000
// PermNixSet, (33554432) indicates that unix permissions have been set
PermNixSet = 0x2000000
// PermExec, (256 or 33562880) the file has the unix executable bit set only meaningful with PermNixSet
PermExec = 0x0000100

An example call looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getActivities","limit":1}'
{
  "status"    : "OK",
  "activities": [
      {
        "Subject"    : "text.txt",
        "Activity"   : 67108864,
        "MicroTime"  : 1450453238116579,
        "Detail"     : "",
        "Actor"      : "user@example.com",
        "BoxName"    : "box1",
        "Detail2"    : "",
        "SubjectType": 41951232,
        "SubjectLong": "folder1/text.txt"
      }
    ]
}

Whereas an empty result set looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getActivities","limit":1,"uid":"foo"}'
{
  "status"    : "OK",
  "activities": []
}

getBoxInfo

This returns a list of boxes that regiboxd currently maintains.

Key Example value Type Description

op

getBoxInfo

string

Get listing of loaded regiboxes.

uids

["3xog…​"]

array

Optional array of uids to get info for.

names

["box1…​"]

array

Optional array of box names to get info for.

fields

[uid, ownerEmail]

array

An optional list of fields to include in the result. One or more one of: corrupted, desc, localOn, microTime, name, ownerEmail, providerUrl, subscriberEmail, uid. When this key is ommitted all fields will be returned.

When both names and uids are specified the result set will contain boxes that satisfy either name or uid requirement. Each box will only be listed once.

Sample call. The result normal comes as a single line and is prettified here for readability:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getBoxInfo"}'
{
  "status": "OK",
  "boxes": [
    {
      "ownerEmail": "example@regify.com",
      "corrupted": 0,
      "localOn": 1,
      "subscriberEmail": "example@regify.com",
      "name": "box1",
      "uid": "3xogaxj3pctns7jig449gwnysx5pypgo",
      "desc": "a first test box",
      "microTime": "1535628778303546",
      "providerUrl": "https://portal.regify.com/"
    }
  ]
}

Here we see the box that we created using newBox along with some relevant information like its uid. For completeness here the same query with a uid and a matching name and a reduced field set in it (all provided as arrays!):

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getBoxInfo", "uids":["3xogaxj3pctns7jig449gwnysx5pypgo"], "names":["box1"], "fields":["name","uid","ownerEmail"]}'
{
  "status": "OK",
  "boxes": [
    {
      "ownerEmail": "example@regify.com",
      "name": "box1",
      "uid": "3xogaxj3pctns7jig449gwnysx5pypgo"
    }
  ]
}

getConfig

Configuration settings may be retrieved one at a time using this call. The actual fields are documented in the newConfig call.

Key Example value Type Description

op

getConfig

string

Retrieve configuration setting.

setting

providerUrl

string

Name of the setting to retrieve.

If all goes well the value is returned under the key specified in setting.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getConfig","setting":"providerUrl"}'
{
  "status"     : "OK",
  "providerUrl": "https://provider.com/"
}

Invalid settings act like the following:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getConfig","setting":"provider"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "failed getting setting provider",
  "ec"    : 77
}

getFileList

This function retrieves a list of files under the given boxPath. It is not considered an error if boxPath specifies something that is not found. In that case an empty list will be returned.

Key Example value Type Description

op

getFileList

string

Get listing of files.

boxPath

box1/folder1

string

Optional path without leading slash starting at the box root. An empty string lists all boxes. To list only a box or its sub folder, you need to enter the boxPath to the desired folder without the trailing slash. Slashes must be of this (/) form.

noFiles

0

integer

Whether to only list folders (1) or everything (0).

recursive

1

integer

Whether to list sub folders as well. If 1 sub folder will be listed under files. If 0 there will be no files field for folders.

filter

0

integer

An optional ORed together value of File Status codes to filter.

File Status

The Status response field contains a number with the following meaning:

// LocalOff, The file is local off
LocalOff  = 0x10
// Uptodate, The file is local on and synchronized
Uptodate  = 0x20
// Uploading, A new version of the file is being uploaded
Uploading  = 0x40
// Downloading, A new version of the file is being downloaded
Downloading  = 0x80
// Subscribed, The file is local on but not yet synchronized
Subscribed  = 0x100
// Unposted, This file has not yet been posted to the server
Unposted  = 0x200
// Unacked, This file has been posted to the server, but the posted record has not yet been pulled
Unacked  = 0x400

Here the sample call is also formated for readability:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getFileList","boxPath":"box1/folder1"}'
{
  "status": "OK",
  "files" : [
      {
        "Size"       : 27,
        "BoxUid"     : "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
        "UtcModDate" : "2018-03-09 14:50:32",
        "BoxPath"    : "box1/folder1/text.txt",
        "ModDate"    : "2018-03-09 15:50:32",
        "BoxName"    : "box1",
        "Id"         : 41,
        "VersionTime": 1520603455175412,
        "FileName"   : "text.txt",
        "Executable" : 0,
        "FilePart"   : "folder1/text.txt",
        "Status"     : 32
      }
    ]
}

A recursive list looks something like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getFileList","boxPath":"upload", "recursive":1,"noFiles":0}'
{
  "status": "OK",
  "files": [
    {
      "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
      "BoxPath": "box1",
      "BoxName": "box1",
      "Files": [
        {
          "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
          "BoxPath": "box1/folder1",
          "BoxName": "box1",
          "Files": [
            {
              "Size": 27,
              "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
              "UtcModDate": "2018-03-09 14:50:32",
              "BoxPath": "box1/folder1/text.txt",
              "ModDate": "2018-03-09 15:50:32",
              "BoxName": "box1",
              "Id": 41,
              "VersionTime": 1520603455175412,
              "FileName": "text.txt",
              "Executable": 0,
              "FilePart": "folder1/text.txt",
              "Status": 32
            }
          ],
          "Id": 16,
          "FileName": "folder1",
          "FilePart": "folder1"
        },
        {
          "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
          "BoxPath": "box1/folder2",
          "BoxName": "box1",
          "Files": [
            {
              "Size": 6878106,
              "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
              "UtcModDate": "2018-03-14 16:35:03",
              "BoxPath": "box1/folder2/DSC_0570.JPG",
              "ModDate": "2018-03-14 17:35:03",
              "BoxName": "box1",
              "Id": 42,
              "VersionTime": 1521041737357505,
              "FileName": "DSC_0570.JPG",
              "Executable": 0,
              "FilePart": "folder2/DSC_0570.JPG",
              "Status": 32
            }
          ],
          "Id": 35,
          "FileName": "folder2",
          "FilePart": "folder2"
        },
        {
          "Size": 27,
          "BoxUid": "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
          "UtcModDate": "2017-04-19 11:57:07",
          "BoxPath": "box1/text.txt",
          "ModDate": "2017-04-19 13:57:07",
          "BoxName": "box1",
          "Id": 13,
          "VersionTime": 1492595845811938,
          "FileName": "text.txt",
          "Executable": 0,
          "FilePart": "text.txt",
          "Status": 32
        }
      ],
      "Id": 1,
      "FileName": "box1",
      "FilePart": ""
    }
  ]
}

In general folders will lack the following fields: Size, UtcModDate, ModDate, VersionTime, Executable and Status. They have the extra Files property only if the listing is recursive.

The VersionTime field is the number of microseconds after epoch (1.1.1970). It is the time when this version was registered at the provider.

The Executable field is set if any one regibox subscriber synchronizes this file to a Posix system (Linux/Mac OSX). When set to 1 then the file will have its executable permission set, else it will be off. This field does not exist if all subscribers use Windows and is generally ignored on Windows.

Finally here’s what happens when we specify something that isn’t there:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getFileList","boxPath":"foo","recursive":1,"noFiles":0}'
{
  "status": "OK",
  "files" : []
}

getInvites

This function retrieves the list of box invitations from the provider. It is equivalent to pressing Manage regiboxes in the desktop client.

Key Example value Type Description

op

getInvites

string

Get listing of regibox invitations.

fields

[uid, boxName]

array

A list of fields to include in the result for each invitation.At least or more one of: uid, boxName, boxDesc, boxPerms, recipEmail, senderEmail, senderName, ownerEmail, inviteDate, rgbxData

uid

3xo…​

string

Optional uid of a specific box invite to retrieve.

query

box1

string

Optional search string that a returned invitation needs to contain. This search is not restricted to the field list requested, but always searches the name, owner email, sender email, sender name and description of a regibox invitation. This field is ignored if uid is given.

The boxPerms field contains an integer describing the users permissions for a given box. This number is described below.

Permission Description

1 (0x1)

Read Only

3 (0x3)

Read/Write

65535 (0xffff)

Administrator can do anything but box deletion.

16777215 (0xff ffff)

Box Owner can do anything with the box and cannot be removed or changed by anybody else.

When neither uid nor query is given, the users entire invitation list will be attempted to be retrieved. Since this does not scale it will be limited to usually 50 entries. When this happens the hasMore field will be set to 1. An example might look like this.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getInvites", "fields": ["boxName","uid"]}'
{
  "status": "OK",
  "invites":[
    {"boxName": "box1","uid":"yes..."},
    {"boxName": "box2","uid":"jtp..."},
    ...
    {"boxName": "box50","uid":"ses..."}
  ],
  "hasMore": 1
}

getMetrics

Returns information about the current users regibox fill level. It returns both the available size and the used size in megabytes (MB). This function performs a login to the regify provider to get the metrics.

Key Example value Type Description

op

getMetrics

string

Return regibox usage info.

This call is user based and only applies to boxes the user owns:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getMetrics"}'
{
  "boxCurrent": 10703.2002,
  "status"    : "OK",
  "boxMax"    : 20480
}

getPastVersion

This function works like recoverVersion but works on files not deleted.

Key Example value Type Description

op

getPastVersion

string

Retrieve a version of a file.

versionId

23

integer

The version to retrieve.

path

/path/to/restore/file.v23

string

Absolute path to where the retrieved file shall be stored. Any folders in this path must already exist. Slashes must be of this (/) form.

A successful call looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getPastVersion", "versionId":5,"path":"/tmp/fileTest"}'
{
  "status": "OK"
}

The retrieved file will be /tmp/fileTest. If the target folder doesn’t exist, it exit like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getPastVersion", "versionId":5,"path":"/foo/bar"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "can't save to non-existing: /foo/",
  "ec"    : 60
}

A nonexistent versionId will return as follows:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getPastVersion", "versionId":500,"path":"/tmp/fileTest"}'
{
  "status": "ERROR",
  "eMsg"  : "A file can not be opened. Please check your paths and user-rights.",
  "desc"  : "failed getting past version of versionId:500",
  "ec"    : 69
}

getRecoveryList

This call returns the list of deleted files in a given box.

Key Example value Type Description

op

getRecoveryList

string

Retrieve a list of deleted files in a regibox.

uid

3xo..

string

The uid of the regibox to get the files from.

A call looks like this:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"getRecoveryList", "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj"}'
{
  "status": "OK",
  "files" : [
      {
        "Size"       : 53,
        "BoxUid"     : "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
        "UtcModDate" : "",
        "BoxPath"    : "box1/folder1/Text.txt",
        "ModDate"    : "",
        "BoxName"    : "box1",
        "DeleteTime" : 1557932615343794,
        "FileId"     : 8,
        "VersionId"  : 18,
        "VersionTime": 1520603391306186,
        "FileName"   : "Text.txt",
        "Executable" : 0,
        "FilePart"   : "folder1/Text.txt",
        "Status"     : 0
      }
    ]
}

An empty result set because of no deleted files or a non existing uid result in the following:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"getRecoveryList"}'
{
  "status": "OK",
  "files" : []
}

getResource

This function retrieves resources that have generally been provided by the regify provider and are internal to libregibox. Currently only Logo.png is supported.

Key Example value Type Description

op

getResource

string

Get a resource.

resourceName

Logo.png

string

Name of the resource to get.

path

/tmp/Logo.png

string

Where to store the resource.

A successful call looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getResource", "resourceName":"Logo.png","path":"/tmp/Logo.png"}'
{
  "status": "OK"
}

There will now be a file /tmp/Logo.png. It is necessary to use absolute file paths since there is no way to infer a current directory. Relative file paths may fail in the following way:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getResource", "resourceName":"Logo.png","path":"Logo.png"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "can't save to non-existing: ",
  "ec"    : 60
}

The same goes for non existing target folders. Assuming there’s no folder named /foo the result will be:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getResource", "resourceName":"Logo.png","path":"/foo/Logo.png"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "can't save to non-existing: /foo/",
  "ec"    : 60
}

If the target folder exists but lacks write permissions we will end up like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getResource", "resourceName":"Logo.png","path":"/Logo.png"}'
{
  "status": "ERROR",
  "eMsg"  : "A file can not be opened. Please check your paths and user-rights.",
  "desc"  : "failed saving resource: Logo.png to /Logo.png",
  "ec"    : 69
}

Finally if something other than Logo.png is tried the result looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getResource", "resourceName":"Banner.png","path":"/tmp/Banner.png"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "failed getting resource: Banner.png",
  "ec"    : 77
}

getUserList

This function retrieves user information.

Key Example value Type Description

op

getUserList

string

Get listing of users.

uid

zqdkecs…​

string

uid of which to get users from. (Optional)

email

user@example.com

string

User by email. (Optional)

A sample call looks like this:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"getUserList",  "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj"}'
{
  "status": "OK",
  "users" : [
      {
        "BoxUid"   : "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
        "Meta"     : "5d0ca85581d4....a717",
        "Name"     : "Mr John Doe",
        "MicroTime": 1486738057935561,
        "Id"       : 1,
        "Notes"    : "regibox Owner",
        "RoleId"   : 5,
        "Activated": 1,
        "Email"    : "user@example.com"
      },
      {
        "BoxUid"   : "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
        "Meta"     : "",
        "Name"     : "Mrs. Jane Doe",
        "MicroTime": 1566398526966236,
        "Id"       : 3,
        "Notes"    : "",
        "RoleId"   : 1,
        "Activated": 0,
        "Email"    : "jane@example.com"
      }
    ]
}

RoleId is documented here➤.

Since it’s assumed that every box should have at least one user empty sets return error 60:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"getUserList", "uid":"foo"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "failed getting user list",
  "ec"    : 60
}

getVersionList

This function retrieves a list of versions for the given fileId and/or filter. Either fileId or filter must be specified. They may also both be specified. It is not considered an error if nothing is found. In that case an empty list will be returned.

Key Example value Type Description

op

getVersionList

string

Get listing of files.

fileId

23

integer

The Id retrieved from a file listing.

filter

0

integer

An optional ORed together value of Version Status codes to filter. When this parameter is set all Version and ParentVersion fields are to be ignored and will be 0.

Version Status

The State response field contains a number with the following meaning:

// NonLocal, This is a past version that is not locally kept
NonLocal  = 0x1
// Current, The is the current version of the corresponding file
Current  = 0x2
// LocalOn, This is a past version that is locally available
LocalOn  = 0x4
// Conflict, This version has the same parent as prior one
Conflict  = 0x8
// Downloading, This version is being downloaded
Downloading  = 0x10
// Subscribed, The version is local on but not yet synchronized
Subscribed  = 0x20
// Unposted, This version has not yet been posted to the server
Unposted  = 0x40
// Unacked, This version has been posted to the server, but the posted record has not yet been pulled
Unacked  = 0x80

Here the sample call is also formated for readability:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getVersionList","fileId":13}'
{
  "status"  : "OK",
  "versions": [
      {
        "Size"         : 27,
        "UtcModDate"   : "2017-04-19 11:57:07",
        "ParentVersion": 2,
        "ModDate"      : "2017-04-19 13:57:07",
        "BoxPath"      : "test1/conf/text.txt",
        "MicroTime"    : 1492595845811938,
        "Version"      : 3,
        "Id"           : 12,
        "FileId"       : 13,
        "State"        : 2,
        "Email"        : "mario.theodoridis@regify.com"
      },
      {
        "Size"         : 114,
        "UtcModDate"   : "2017-04-19 11:55:22",
        "ParentVersion": 1,
        "ModDate"      : "2017-04-19 13:55:22",
        "BoxPath"      : "test1/conf/text.txt",
        "MicroTime"    : 1492595767752536,
        "Version"      : 2,
        "Id"           : 11,
        "FileId"       : 13,
        "State"        : 1,
        "Email"        : "mario.theodoridis@regify.com"
      },
      {
        "Size"         : 114,
        "UtcModDate"   : "2017-04-10 14:37:05",
        "ParentVersion": 0,
        "ModDate"      : "2017-04-10 16:37:05",
        "BoxPath"      : "test1/conf/text.txt",
        "MicroTime"    : 1491827843830378,
        "Version"      : 1,
        "Id"           : 8,
        "FileId"       : 13,
        "State"        : 1,
        "Email"        : "mario.theodoridis@regify.com"
      }
    ]
}

The State field contains a bit field number with the following meaning:

And here’s what happens when we specify something that isn’t there:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"getVersionList","fileId":14}'
{
  "status"  : "OK",
  "versions": []
}

invite

This is used to invite members to a regibox.

Key Example value Type Description

op

invite

string

Invite a member to a regibox.

uid

3xo..

string

The uid of the regibox to which to invite the member.

roleId

4

integer

The access rights the new member gets. One of 1 = admin, 3 =read, 4 = read/write

email

user@example.com

string

Email of the person to invite.

name

Don Example

string

Optional name of the person to invite.

notes

A sample box

string

Optional notes regarding this account.

subject

Your invitation

string

Optional subject for the invitation e-mail. If not set, the default invitation template subject is used. If body is also specified, that default may not exist and the subject will be blank unless specified here.

body

<!DOCTYPE (…​)><html><body>…​

string

Optional e-mail body for the invitation. If not set, the default template for the current locale is used.

message

Hi John, please accept…​

string

Optional personal message. It will replace any [MESSAGE] placeholders in the body template. The default body template contains this placeholder for an individual message to the recipient.

rgbxPath

/path/to/invite.rbgx

string

Optional path to place invitation at instead of sending it via e-mail. The enclosing folder must already exist.

We start out with a bad invitation:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"invite", "roleId":4, "name":"John Sample","notes":"a test note", "message":"Hello John\nhere is your invitation.", "email":"\example@regify.com"}'
{
  "status": "ERROR",
  "eMsg"  : "The given uid is invalid",
  "desc"  : "failed inviting user:John Sample",
  "ec"    : 326
}

We forgot to set the uid, so regiboxd doesn’t know which box:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"invite", "roleId":4, "name":"John Sample","notes":"a test note", "message":"Hello John\nhere is your invitation.", "email":"\example@regify.com", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo"}'
{
  "status": "OK"
}

This time it worked out and John should have an invitation e-mail in his inbox. Another example with an invalid role id:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"invite", "roleId":5, "name":"John Sample","notes":"a test note", "message":"Hello John\nhere is your invitation.", "email":"\example@regify.com", "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj"}'
{
  "status": "ERROR",
  "eMsg"  : "The given role id is invalid.",
  "desc"  : "",
  "ec"    : 329
}

localOnOff

This function controls whether local copies of files are kept, or not.

Key Example value Type Description

op

localOnOff

string

Whether to maintain a local copy of a file.

uid

3xo…​

string

The uid of the box to where the files are in.

filePart

path/to/file

string

The relative path to the file or folder to turn on or off. In case of a folder, all files and folder in that folder will be affected. This path is relative to the regibox it is in excluding the box name. So for a top level file in box1 named example.txt the filePart parameter would be example.txt and not box1/example.txt. To affect box1 itself, the filePart should be an empty string or left out altogether.

isOn

1

integer

Whether to have a local copy (1) or not (0).

Here’s a sample where we just turn 1 file foo off:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"localOnOff", "uid":"srp79f915967u3doyd8o7orfikjyn5d8", "filePart":"foo","isOn":0}'
{
  "status": "OK"
}

In the next example we’ll simply turn local copies on the entire box back on:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"localOnOff", "uid":"srp79f915967u3doyd8o7orfikjyn5d8", "filePart":"","isOn":1}'
{
  "status": "OK"
}

The empty filePart indicates the top folder of a regibox meaning everything from there on below is turned on.

logging

This simply turns debug logging on or off and allows specifying where the log is to be written to. It is an alternative to specifying -l debug.log -v on the command line. Unlike the diagnostics calling this only controls debug logging and does not sanitize any sensitive data. Logs generated via these means most likely contain sensitive data.

Key Example value Type Description

op

logging

string

Start or stop debug logging.

filePath

/path/to/debug.log

string

Absolute path where to write the debug log to. This is optional and ignored when the logLevel is set to NONE. This path is subject to the same rules as the -l parameter and therefore dynamic tokens like +P can be used. For more info run regiboxd without any parameters or with the -h switch to see -l under GENERAL OPTIONS. The folder up to the filePath will be created, or an error (85) is returned if this is not possible.

level

WARN

string

Optional desired log level. One of CRIT, WARN, INFO, VERB or NONE. When set to NONE logging is turned off and filePath is ignored. When this is omitted and filePath is given it is assumed to be VERB. If filePath is also omitted, logging is simply turned off.

This example call turns on verbose logging:

$ ./regiboxctl -c test1/conf/ -j '{"op":"logging","filePath":"/tmp/box.log"}'
{"status": "OK"}

This is how to turn it off again:

$ ./regiboxctl -c test1/conf/ -j '{"op":"logging"}'
{"status": "OK"}

newBox

Creates a new regibox on the given regiboxd instance.

Key Example value Type Description

op

newBox

string

Create a new regibox.

name

box1

string

Name of the box to create.

desc

a first test box

string

Optional description for the box.

importExisting

0

integer

Optional, whether to import the folder if it already exists in the file system. Default is 0.

Sample calls look like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newBox","name":"box1", "desc":"a first test box"}'
{
  "status": "OK",
  "uid"   : "x54hdqdrr7x4hybgk3c9d4furdh38kg6"
}

The returned uid may be empty if the box was created but not posted to the server, due to network or other issues. The box name must be unique. If we try this again:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newBox","name":"box1", "desc":"a first test box"}'
{
  "status": "ERROR",
  "eMsg"  : "There's already a box by that name",
  "desc"  : "box1",
  "ec"    : 301
}

Invalid box names look like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newBox","name":"con"}'
{
  "status": "ERROR",
  "eMsg"  : "The given box name is invalid",
  "desc"  : "con",
  "ec"    : 328
}

Also worth noting are already existing box folders:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newBox","name":"foo"}'
{
  "status": "ERROR",
  "eMsg"  : "There's already a folder by that name",
  "desc"  : "foo, set importExisting to import it.",
  "ec"    : 302
}

newConfig

Creates a new configuration for the regiboxd instance.

Key Example value Type Description

op

newConfig

string

Description of the desired operation.

locale

en

string

Optional country code of used locale. Currently one of en, de, fr or cn. Default en.

boxRoot

Deprecated

Ignored and logs a warning in newConfig but returns an error in setConfig. This is now set on initial instance start via the -r switch.

enableNetworkMode

0

integer

Optional whether box root get file access monitoring events or not. A network share sometimes does not.

networkMode

241

integer

Optional the eagerness with which to monitor the folders. 240 = lazy, 241 = standard, 242 = aggressive

speedDownload

0

integer

Optional desired download bandwidth limit in kilo bytes. 0 for none.

speedUpload

0

integer

Optional desired upload bandwidth limit in kilo bytes. 0 for none.

providerUrl

https://provider.com/

string

The URL to the regify provider.

regifyUser

user@domain.com

string

The user login for the regify account. Usually the same as e-mail.

regifyPass

mysecret

string

The password for the regify account.

proxySelection

0

integer

Optional. The type of proxy to use. 0 = none, 1 = static & 2 = PAC file.

proxyServer

myproxy:3128

string

Optional address of proxy server when proxySelection is 1.

proxyPacFile

http://pachost/pac

string

Optional file path or URL to pac file to use when proxySelection is 2.

proxyUser

user

string

Optional user account for the proxy when it is enabled.

proxyPass

mysecret

string

Optional proxy password when proxy is enabled and credentials are required.

smtpServer

mail.domain.com

string

Optional host address of an SMTP server for sending out invitations. Requires smtpSender to be set as well.

smtpPort

25

integer

Optional port of the SMTP server.

smtpUseTls

1

integer

Optional, whether to use TLS (1) or not (0).

smtpIgnoreSslError

0

integer

Optional, whether to ignore certificate errors such as name mismatches (1) or not (0).

smtpSender

user@domain.com

string

Address the appears in the from header of a sent invitation, used when SMTP is enabled.

replyTo

user@domain.com

string

Optional address that appears in the reply to header of a sent invitation.

smtpUser

user@domain.com

string

Optional user login for sending invitation if the mail server requires it.

smtpPass

mysecret

string

Optional password to along with the smtpUser field.

smtpCopyMe

0

integer

Optional, whether to send a copy of every invitation to the e-mail of the regify user.

keepRemovedBoxes

0

integer

Optional, whether to keep copies of removed regiboxes in the file system.

eventsToSyslog

0

integer

Optional, whether to log important events to syslog. Defaults to 1.

eventLogPath

c:/regibox/events.log

string

Optional, where to write important events to.

Below are some example calls done using regiboxctl along with their results:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "providerUrl":"https://prtl.regify.com","regifyUser":"\example@regify.com", "regifyPass":"mysecret"}'
{
  "status": "ERROR",
  "eMsg"  : "Can not connect to the regify provider.",
  "desc"  : "failed to save configuration",
  "ec"    : 58
}

Above call failed with error code 58 because we typed the providerUrl wrong.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "providerUrl":"https://portal.regify.com","regifyUser":"\example@regify.com", "regifyPass":"wrongsecret"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid login or password.",
  "desc"  : "failed to save configuration",
  "ec"    : 10
}

This time we got error code 10 because we had the wrong password.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "boxRoot":"/regibox/root/", "providerUrl":"https://portal.regify.com","regifyUser":"\example@regify.com", "regifyPass":"mysecret"}'
{
  "status": "OK"
}

Here we did everything right and end up with a valid running regiboxd instance.

Now we’ll try some SMTP settings:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "boxRoot":"/regibox/root/", "providerUrl":"https://portal.regify.com","regifyUser":"\example@regify.com", "regifyPass":"mysecret","smtpServer":"smtp.regify.com","smtpSender":"\example@regify.com"}'
{
  "status": "ERROR",
  "eMsg"  : "Internet connection problem",
  "desc"  : "failed to validate SMTP configuration:SSL peer certificate or SSH remote key was not OK Details(SSL: no alternative certificate subject name matches target host name 'smtp.regify.com') curl ec:51",
  "ec"    : 58
}

Ok, smtp.regify.com probably has a different real name and that’s on the cert, so we’ll go with "That’s expected" here.

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "providerUrl":"https://portal.regify.com","regifyUser":"\example@regify.com", "regifyPass":"mysecret","smtpServer":"smtp.regify.com", "smtpSender":"\example@regify.com","smtpIgnoreSslError":1}'
{
  "status": "ERROR",
  "eMsg"  : "Internet connection problem",
  "desc"  : "failed to validate SMTP configuration:Failed sending data to the peer Details(RCPT failed: 550) curl ec:55",
  "ec"    : 58
}

Nothing but trouble, I guess, we have to authenticate. If unsure turn on logging via the command line or by sending diagnostics before and after and looking at the logs. So let’s add authentication as well:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"newConfig", "providerUrl":"https://portal.regify.com","regifyUser":"\example@regify.com", "regifyPass":"mysecret","smtpServer":"smtp.regify.com", "smtpSender":"\example@regify.com","smtpIgnoreSslError":1, "smtpUser":"\example@regify.com","smtpPass":"mysmtpsecret"}'
{
  "status": "OK"
}

Now we have a valid configure regiboxd instance that sends its own e-mails instead of relaying them off of the regify provider. example@regify.com will also have a test e-mail in their inbox.

recoverVersion

This function allows retrieving a specific version of a deleted file. It is an asynchronous call meaning that the resulting file will most likely arrive at a later time than the result of the call.

Key Example value Type Description

op

recoverVersion

string

Recover a version of a deleted file.

versionId

23

integer

The version to recover.

path

c:/regibox/file.v23

string

Absolute path under which the recovered file shall be stored. Any folders in this path must already exist. Slashes must be of this (/) form.

Provided the folder restore/ exists, a successful call looks like this:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"recoverVersion","versionId":23, "path":"c:/regibox/file.v23"}'
{
  "status":"OK"
}

Whereas a failure due to non-existent restore/23/ folder looks like this:

$ ./regiboxctl -c test1/conf/ -p  -j '{"op":"recoverVersion","versionId":23, "path":"restore/23/file"}'
{
  "status":"ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc":"can't recover into non-existing: restore/23/",
  "ec":60
}

Similar things happen when path is not writable except that the answer will be OK and there will be an entry in your syslog along the lines of:

Sep 25 10:52:22 dev regiboxd[222]: CRIT: Failed to move /home/user/test1/conf/li...j/93/text_1.txt to /bar

and the file will of course not be there.

resetConfig

This call removes all regiboxes from the db and, if intended, from the filesystem and clears all relevant login data.

Key Example value Type Description

op

resetConfig

string

Reset the configuration.

keepLocal

0

integer

If 1, leaves local regiboxes in the file system and preserves non regify ini settings. If missing or 0, local regiboxes and ini files are deleted from the file system.

Here is what a successful call looks like:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"resetConfig","keepLocal":1}'
{
  "status": "OK"
}

restoreFile

This function is similar to recoverVersion expect that it tries to restore the latest version of a file in the recovery bin to its original location.

Key Example value Type Description

op

restoreFile

string

Restore latest version of a deleted file.

fileId

23

integer

The file id to restore. The id is as obtained from getRecoveryList.

A successful call looks as usual:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"restoreFile","fileId":4}'
{
  "status": "OK"
}

Whereas a failure in case the file already exists looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"restoreFile","fileId":4}'
{
  "status": "ERROR",
  "eMsg"  : "The file already exists and cannot be overwritten.",
  "desc"  : "failed restoring fileId:4",
  "ec"    : 324
}

resubscribeBox

Here we reload a box that has been removed with unsubscribeBox.

Key Example value Type Description

op

resubscribeBox

string

Keep a regibox locally.

uid

3xo…​

string

The uid of the box to resubscribe.

localOn

1

integer

Optional, whether to have local copies of the files for this box. Default is 1.

name

box1_2

string

Optional alternative box name. Useful when another box by the default name already exists.

This is equivalent to manage a regibox on in the regibox desktop manager:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"resubscribeBox", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo"}'
{
  "status": "ERROR",
  "eMsg"  : "That box name is used by another box",
  "desc"  : "failed resubscribing box uid:3xogaxj3pctns7jig449gwnysx5pypgo",
  "ec"    : 306
}

It seems that box name is already taken, so choose another:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"resubscribeBox", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo","name":"new box1"}'
{
  "status": "OK"
}

Now we succeed. Let’s try it again:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"resubscribeBox", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo","name":"new box1"}'
{
  "status": "ERROR",
  "eMsg"  : "There's already a box by that name.",
  "desc"  : "new box1",
  "ec"    : 301
}

It states the obvious.

setConfig

In addition to newConfig, individual settings may be set as well. The API is similar to getConfig. The actual fields are documented in the newConfig call.

Key Example value Type Description

op

getConfig

string

Retrieve configuration setting.

setting

providerUrl

string

Name of the setting to retrieve.

value

https://other.provider.com

string

The new value of the setting.

A successful run looks like this:

$ ../regiboxctl -c test1/conf/ -p -j '{"op":"setConfig","setting":"providerUrl", "value":"https://lindev.de.regify.com/"}'
{
  "status": "OK"
}

A failing call like this:

$ ../regiboxctl -c test1/conf/ -p -j '{"op":"setConfig","setting":"provider", "value":"https://lindev.de.regify.com/"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "couldn't set field",
  "ec"    : 77
}

setUser

setUser allows making changes to user accounts.

Key Example value Type Description

op

setUser

string

Change a user property.

uid

zqdkecs…​

string

The uid where the user is a member.

email

user@example.com

string

User email.

setting

notes

string

The property to set. One of name notes, meta, roleId or revoke.

value

test setting

string/integer

The new value of the setting. This field is ignored with revoke as that simply deletes the user account. roleId expects an integer while everything else expects a string.

A sample call looks like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"setUser", "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj", "email":"\user@example.com","setting":"notes","value":"test"}'
{
  "status": "OK",
  "dirty" : 1
}

The dirty flag indicates whether the setting has actually changed, so a repeated call will look like this:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"setUser", "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj", "email":"\user@example.com","setting":"notes","value":"test"}'
{
  "status": "OK",
  "dirty" : 0
}

When errors happen they depend on their nature. An invalid uid shows up as the following:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"setUser","uid":"foobar", "email":"\user@example.com","setting":"notes","value":"test"}'
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "uid is invalid",
  "ec"    : 77
}

Error 48 is box not found. Where as a not found users exhibit error 60 which technically speaking is file not found:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"setUser","uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj", "email":"\wrong@address.com","setting":"notes","value":"test"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "Failed setting user field",
  "ec"    : 60
}

Then finally there are permission issues such as the acting user does not have the user permission to make changes:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"setUser","uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj", "email":"\user@domain.com","setting":"notes","value":"test2"}'
{
  "status": "ERROR",
  "eMsg"  : "You do not have enough permissions to complete this operation",
  "desc"  : "Failed setting user field",
  "ec"    : 206
}

Here error 206 specifically states "The user does not have enough permissions to complete this operation".

User Roles

The RoleId field contains a number with the following meaning:

// Admin, Admin access.
Admin  = 1
// Read, Read only access.
Read  = 3
// Write, Read/write access.
Write  = 4
// Owner, Box owner. Cannot be altered.
Owner  = 5

unsubscribeBox

This is called to stop keeping a regibox locally and not to delete it.

Key Example value Type Description

op

unsubscribeBox

string

Stop keeping a regibox locally.

uid

3xo…​

string

The uid of the box to unsubscribe.

A sample call looks like:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"unsubscribeBox", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo"}'
{
  "status": "OK"
}

A repeated call will fail as follows:

$ ./regiboxctl -c test1/conf/ -j '{"op":"unsubscribeBox", "uid":"3xogaxj3pctns7jig449gwnysx5pypgo"}'
{
  "status": "ERROR",
  "eMsg"  : "The regibox could not be found.",
  "desc"  : "failed unsubscribing box uid:zqdkecs1uw5bigdnoccrs4ngkuknsytj",
  "ec"    : 48
}

zapPast

This function removes all past versions of a file and adds the file as a new file. It is generally used to clean up extra storage space when older versions are no longer needed.

Key Example value Type Description

op

zapPast

string

Remove all older versions of a file.

uid

3xo…​

string

The uid of the box to where the files are in.

filePart

path/to/file

string

The relative path to the file to zap the old versions of. This path is relative to the regibox it is in excluding the box name. So for a top level file in box1 named example.txt the filePart parameter would be example.txt and not box1/example.txt.

So here we try this with an invalid uid:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"zapPast", "uid":"srp79f915967u3doyd8o7orfikjyn5d","filePart":"bar"}'
{
  "status": "ERROR",
  "eMsg"  : "The regibox could not be found.",
  "desc"  : "failed deleting past versions of:test-2.txt",
  "ec"    : 48
}

It tells us. Next, the filePart is invalid:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"zapPast", "uid":"srp79f915967u3doyd8o7orfikjyn5d8","filePart":"bar"}'
{
  "status": "ERROR",
  "eMsg"  : "File not found: <VAL1>",
  "desc"  : "failed deleting past versions of:zoo",
  "ec"    : 60
}

It complains about that as well:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"zapPast", "uid":"srp79f915967u3doyd8o7orfikjyn5d8","filePart":"foo"}'
{
  "status": "OK"
}

Here we did everything right. Here’s what happens if bar is a folder:

$ ./regiboxctl -c test1/conf/ -p -j '{"op":"zapPast", "uid":"zqdkecs1uw5bigdnoccrs4ngkuknsytj","filePart":"bar"}'
{
  "status": "ERROR",
  "eMsg"  : "The given path is a folder.",
  "desc"  : "cannot zap past of folders",
  "ec"    : 327
}