Documentation and help portal

★ Home
regiboxd
Version 3.0
Windows Reference Manual
Deutsch
Français
regiboxd Specification

Introduction Windows

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.exe, which stands for regibox daemon. Here it is also known as a service, and it is implemented that way but nevertheless called regiboxd.exe. regiboxd.exe is available for 64 bit Windows and Linux amd64/x86_64 architectures.

regiboxd.exe ships with a control application called regiboxctl.exe. regiboxctl.exe can be used as a convenience tool to control a given regiboxd.exe instance. Instances are created with their individual configuration directories, which are unique to every regiboxd.exe 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.

regiboxd.exe 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.exe. 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.exe instance is sufficient.

Changes

To find changes in a new version use the search function of your browser with the relevant version such as version 3.0

The Service

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.exe from the command line will respond with the help screen complaining about a missing configuration directory. This help will look something like this, but it’s best to run regiboxd.exe without any parameters or with the -h switch to see an up to date version for your given platform.

regiboxd.exe - Version 3.0.0-14132 (c) 2015-2025 regify GmbH

regiboxd.exe is designed to run as a 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.
    -I Specify the unique service name as which run the service as. (internal)
    -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.

Installing an instance

To be able to run as a Windows service, a regiboxd.exe 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 the presence of the folder C:\regibox.

C:\> "C:\Program Files\regiboxd\regiboxd.exe" -c "C:\regibox\config" -r "C:\regibox\root" -i "MyRegiboxInstance" -d "A test regiboxd instance"
Service test1 has been successfully installed.

The -d switch is optional. The folder config and the necessary sub folders will be created. Instead of config it could have also been config\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:\> "C:\Program Files\regiboxd\regiboxd.exe" -L
Currently installed regiboxd service instances. Name, Command line, ACTIVE(pid) means running
MyRegiboxInstance (1828)   "C:\Program Files\regiboxd\regiboxd.exe" -I "regiboxd_MyRegiboxInstance" -c "C:\regibox\config"

Here we see that our service MyRegiboxInstance is running with process id 1828 and configuration directory C:\regibox\config, 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.exe services that start with regiboxd_, they will be listed as well. Administrating them with regiboxd.exe is obviously not recommended. Finally, to uninstall an instance again we do the following:

C:\> "C:\Program Files\regiboxd\regiboxd.exe"  -u MyRegiboxInstance
Service MyRegiboxInstance has been successfully deleted.

Sometimes a service lingers after de-installation. 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

Using command line tool regiboxctl

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

regiboxctl.exe - regibox Manager Version 3.0.0-14132 (c) 2015-2025 regify GmbH


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

  OPTIONS:
    -c Config directory. Same as the -c option of the regiboxd 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. Adds "prettyPrint": 1 to the request
    -t Optional time to wait for an answer, defaults to 5 seconds.

regiboxctl.exe 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.

Control using filesystem

Communication with a regiboxd.exe 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.exe doesn’t try to read the file before we’re done writing it.

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

This file should contain UTF-8 encoded JSON as described in the chapter below. In the odd circumstance where the regiboxd.exe 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:\regibox\config\res\response.tmp
and
C:\regibox\config\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 the event log. 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:\regibox\config\req\request.1234.tmp
followed by a rename to
C:\regibox\config\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:\regibox\config\res\response.1234.tmp
and
C:\regibox\config\res\response.1234

General Notes

The examples in this document are done using regiboxctl.exe on a DOS shell. This is a typical call and some error message:

Windows DOS Syntax

regibox will accept both Windows \ and Unix style / file slashes in its parameters and JSON. The latter need no escaping.

Because the Windows DOS shell and the Powershell struggle with single and double quotes, regiboxctl.exe 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:

The drawback of the -J switch is that you cannot use single quotes in your JSON parameters at all! 
C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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>.

First steps with regiboxd

Starting your first regibox instance on Windows

  • After you downloaded the installer, please run and finish the setup.

  • Open a commandline prompt with Administrator permissions.

You may want to increase the window size in the properties (top left menu) by increasing Screen Buffer Size Width to 160.

  • Go to the root folder of your drive:

C:\Windows\System32> cd C:\

  • Create a directory as your instance folder. It will hold your future regibox configuration:

C:\> mkdir C:\regibox
C:\> mkdir C:\regibox\config

  • Create a root folder as root for your regiboxes:

C:\> mkdir C:\regibox\root
You must not use the same folder for configuration and data!

  • Register your regiboxd.exe as service:

C:\> "C:\Program Files\regiboxd\regiboxd.exe" -c "C:\regibox\config" -r "C:\regibox\root" -i "MyRegiboxInstance"

  • Please note that we submit the previously created config folder with -c and the regibox root folder with -r.

  • The -i switch registers your new regiboxd.exe as service with the name MyRegiboxInstance.

  • If you don’t get Service MyRegiboxInstance has been successfully installed, ensure that you run the commandline with administrator permissions.

    • Validate the service by listing all regiboxd.exe services:

      C:\> "C:\Program Files\regiboxd\regiboxd.exe" -L
Currently installed regiboxd service instances. Name(pid) means running, Command line
MyRegiboxInstance (984) "C:\Program Files\regiboxd\regiboxd.exe" -I "regiboxd_MyRegiboxInstance" -c "C:\regibox\config"

Configure your instance

  • Configure your new regibox service with your credentials. See newConfig➤ for details.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'newConfig', 'providerUrl':'https://regify.provider.com', 'regifyUser':'user@example.com', 'regifyPass':'mysecret'}"

  • You should get the following json result. If you get an error, validate your request.

{"status": "OK"}

Create your first box

  • Create your first regibox like this. See newBox➤ for details.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'newBox', 'name':'box1'}"

  • You should get something like the following json result showing status OK and a uid, which is the API identifier of the new regibox. If you get an error, validate your request.

{"status": "OK", "uid" : "xksiypdqycmd7dhr6s8tbyqx8qsdcfnw"}

Congratulations, you have just created your first regibox.

Uninstall a Windows regiboxd instance

In order to unregister a regiboxd instance, call regiboxd with the -u option:

C:\> "C:\Program Files\regiboxd\regiboxd.exe" -u "MyRegiboxInstance"

This removes the service and regiboxd is no longer running on the folders. Please note that this neither deletes the regibox nor the local data. It just stops and unregisters the service.

You can re-register the service at any time on the existing configuration and data like this:

C:\> "C:\Program Files\regiboxd\regiboxd.exe" -c "C:\regibox\config" -i "MyRegiboxInstance"
If a config is already existing, you can omit the -r setting like in this example call.
When you upgrade regiboxd.exe, first unregister all running regiboxd.exe instances, update your software and re-register the services.
Sometimes you may need to start the regiboxd.exe service manually after it was unregistered and re-registered. Use Windows Service management for this. You can also try net start MyRegiboxInstance.

Examples

Below are steps to accomplish certain tasks.

Updating regiboxd.exe

In order to upgrade your current regiboxd.exe installation, follow these steps. Check for changes in this version.

Creating a Diagnostics

If you were asked to send a diagnostics by regify support or your regify provider support, you can start and stop diagnostics like this. See diagnostics➤ for details.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'diagnostics'}"
{"status":"OK","desc":"diagnostics started"}

To stop it, run the same again

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'diagnostics'}" -t 120
{"status":"OK","desc":"Diagnostics written to C:\regibox\config\lib\tmp\regibox-diagnostics.zip"}
The -t switch increases the timeout of regiboxctl.exe to last for 120 seconds. On big regiboxes, it might need even more time.
Even if the regiboxctl.exe tool times out, it does not mean that regiboxd.exe stopped execution of the call. Longer lasting calls run in the background until they finish, independent of the regiboxctl.exe tool.

Debugging / Logfile

In order to investigate issues, for example connectivity, or after you have been asked by regify support, the following command enables the debug log. filePath should be set to a location that is known to be writable by regiboxd.exe. See logging➤ for details.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'logging', 'filePath':'C:/box-+D.log'}"

Please note that a backslash in json must be escaped with \ (becoming a double backslash).

You can turn off logging by the same call but without a filePath value:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'logging'}"

Empty Recovery Folder of all Boxes

First get the uids of all boxes using getBoxInfo➤ API function.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getBoxInfo','fields':['uid']}"
{
  "status": "OK",
  "boxes": [
    {
      "uid": "jbyt1xpuqf3mu5hauau85ferzr5jytpt"
    },
    {
      "uid": "z6pryo8n5fmyiydb1u9ooaihqener547"
    },
    {
      "uid": "3xogaxj3pctns7jig449gwnysx5pypgo"
    }
  ]
}

Now run emptyRecovery➤ for each one like in this example call.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'emptyRecovery', 'uid':'jbyt1xpuqf3mu5hauau85ferzr5jytpt'}"
{"status": "OK"}

Delete past versions of a set of files

First get the files to delete by calling getFileList➤ function.

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

  • Set filter to Current (32) as the file needs to be local on and up to date.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getFileList','boxPath':'box1','filter':32}"
{
  "files": [
    {
      "FileId": 1691229,
      "FolderId": 1,
      "BoxName": "box1",
      "BoxUid": "o93cgtbyqio8s7zf11fp1quoyry9ejt4",
      "FilePart": "4otd5hbxtu8k",
      "BoxPath": "box1/4otd5hbxtu8k",
      "FileName": "4otd5hbxtu8k",
      "VersionId": 1868602,
      "ModDate": "2024-12-16 11:23:32",
      "UtcModDate": "2024-12-16 10:23:32",
      "Size": 91844,
      "VersionTime": 0,
      "Status": 32,
      "Executable": 0
    },
    {
      "FileId": 7516,
      "FolderId": 1,
      "BoxName": "box1",
      "BoxUid": "o93cgtbyqio8s7zf11fp1quoyry9ejt4",
      "FilePart": "9y3zs1r44qfg",
      "BoxPath": "box1/9y3zs1r44qfg",
      "FileName": "9y3zs1r44qfg",
      "VersionId": 1545967,
      "ModDate": "2024-12-12 19:30:08",
      "UtcModDate": "2024-12-12 18:30:08",
      "Size": 27343,
      "VersionTime": 1734087716780563,
      "Status": 32,
      "Executable": 0
    },
    {
      "FileId": 12,
      "FolderId": 1,
      "BoxName": "box1",
      "BoxUid": "o93cgtbyqio8s7zf11fp1quoyry9ejt4",
      "FilePart": "eunzfht77",
      "BoxPath": "box1/eunzfht77",
      "FileName": "eunzfht77",
      "VersionId": 1868609,
      "ModDate": "2025-02-05 16:44:40",
      "UtcModDate": "2025-02-05 15:44:40",
      "Size": 5945,
      "VersionTime": 0,
      "Status": 32,
      "Executable": 0
    }
  ],
  "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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -J "{'op':'zapPast', 'uid':'o93cgtbyqio8s7zf11fp1quoyry9ejt4','filePart':'9y3zs1r44qfg'}"
{"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/regibox.ini or configuration folder/regiboxd.ini for older versions, 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 afterward.

  • 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 password. 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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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.exe 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.

File Path Naming

There are 2 common ways to name file paths to indicate which addressing mode is meant.

  • boxPath or BoxPath - this starts below the regibox root folder - boxname/file/path

  • filePart or FilePart - this starts below a given regibox - file/path

All other path references generally mean either absolute or relative filesystem paths.

Common parameters

Besides the op parameter there a other fields that have meaning in all calls.

Key Example value Type Description

op

shoeShine

string

The operation requested.

prettyPrint

1

integer

Whether to pretty print the response (1). Default is 0. Added in version 3.0.

indent

"\t"

string

Optional string to customize the indentation of the pretty printed response when prettyPrint is set. Added in version 3.0.

Only the following characters are allowed \n, \v, \f, \t, \r and ' '

escapeSlashes

1

integer

Whether to escape / in the response (1). Default is 0. Added in version 3.0.

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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'acceptInvite','localOn':1,'data': 'Type=regibox\nRecipient=user@example.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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'acceptInvite','localOn':1,'data': 'Type=regibox\nRecipient=user@example.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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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 will simply delete your invitation to it and 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'deleteBox', 'uid':'4mudnc44a89q7k5g76379mxnz1tykibt'}"
{
  "status": "OK"
}

Nothing to it.

Deleting nonexistent boxes no longer returns an error in version 3.0

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.exe. 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.exe with the -D flag to catch issues that happen during startup.

Key Example value Type Description

op

diagnostics

string

Start or stop diagnostics mode.

abort

1

integer

Optional parameter to insure diagnostics mode is stopped in case it is running. When this is set to 1, diagnostics mode will not be started.

abort was added in version 3.0.

destZipPath

/path/to/diag.zip

string

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

A first example call to show the behavior of abort when diagnostics are not running:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'diagnostics', 'abort': 1}"
{
  "status": "OK",
  "desc": "diagnostics were not running"
}

Here we start it:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'diagnostics'}"
{
  "status": "OK",
  "desc"  : "diagnostics started"
}

And to stop we issue the same:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'diagnostics', 'abort': 1}"
{
  "status": "OK",
  "desc"  : "Diagnostics written to C:\regibox\config\lib\tmp\regibox-diagnostics.zip"
}

It returns the full path in description. The abort parameter was optional at this point. When specifying the path as a relative path it will be based off of the working path of the regiboxd.exe executable not the caller, so full paths are generally recommended.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'diagnostics', 'destZipPath':'/test-diagnostics.zip'}"
{
  "status": "ERROR",
  "desc"  : "Failed writing to destZipPath. Diagnostics written to C:\regibox\config\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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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

Time after which the activity occurred. Format is microseconds since 1-1-1970.

activityType

1

integer

An optional ORed together value of Activity Type➤ to filter.

limit

100

integer

The maximum number of activities to retrieve.

Activity Types

The activityType field is defined as follows:

// (1) The file has been deleted.
FileDeleted = 0x001
// (2) The file name has been changed.
FileName = 0x002
// (4) The file permissions (executable for posix only) have been changed.
FilePerms = 0x004
// (8) The file has been permanently deleted from the server.
FilePurged = 0x008
// (16) The user permissions have been changed.
UserRole = 0x010
// (32) The username has been changed.
UserName = 0x020
// (64) The user notes have been changed.
UserNotes = 0x040
// (256) The user account has been revoked.
UserRevoke = 0x100
// (1024) The user account has been activated.
UserActive = 0x400
// (2048) The user metadata was changed.
UserMeta = 0x800
// (4096) The folderId nodeId pair for a given fileId is being delivered to
// facilitate migration by supplementing this missing info.
// *
// This event is transient and not stored in the boxes history.
FolderInfo = 0x1000
// (16777216) The box has been created.
NewBox = 0x01000000
// (33554432) A new user has been invited.
NewUser = 0x02000000
// (67108864) A new file has been created.
NewFile = 0x04000000
// (134217728) A new version of a file has been created.
NewVersion = 0x08000000
// (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

user@example.com

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.

// (8388608) This file has been deleted
Deleted = 0x0800000
// (16384) This is a folder
Folder = 0x0004000
// (8192 or 33562624) This is a file
File = 0x0002000
// (33554432) indicates that unix permissions have been set
NixSet = 0x2000000
// (256 or 33562880) the file has the unix executable bit set only meaningful with RGB_perm_NixSet
Exec = 0x0000100

An example call looks like this:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getActivities','limit':1}"
{
  "status"    : "OK",
  "endTime"  : 1450453238000000,
  "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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getActivities','limit':1,'uid':'foo'}"
{
  "status"    : "OK",
  "endTime"  : 1450453238000000,
  "activities": []
}

In each case endTime is the maximum micro timestamp the listed events may have (aka ⇐ endTime). This time is a few seconds before the current time. The endTime field appeared in version 3.0.

getBoxInfo

This returns a list of boxes that regiboxd currently subscribes.

Key Example value Type Description

op

getBoxInfo

string

Get listing of subscribed 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getBoxInfo'}"
{
  "status": "OK",
  "boxes": [
    {
      "ownerEmail": "user@example.com",
      "corrupted": 0,
      "localOn": 1,
      "subscriberEmail": "user@example.com",
      "name": "box1",
      "uid": "3xogaxj3pctns7jig449gwnysx5pypgo",
      "desc": "a first test box",
      "microTime": "1535628778303546",
      "providerUrl": "https://regify.provider.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!):

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getBoxInfo', 'uids':['3xogaxj3pctns7jig449gwnysx5pypgo'], 'names':['box1'], 'fields':['name','uid','ownerEmail']}"
{
  "status": "OK",
  "boxes": [
    {
      "ownerEmail": "user@example.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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getConfig','setting':'providerUrl'}"
{
  "status"     : "OK",
  "providerUrl": "https://regify.provider.com"
}

Invalid settings act like the following:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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 boxPath 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). Optional, defaults to 0.

foldersOnTop

0

integer

Whether to list folders above files (not 0). Optional, defaults to 0. Ignored when recursive is set. Added in version 3.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. Optional, defaults to 0.

filter

0

integer

An optional ORed together value of File Status➤ codes to filter. Ignored when recursive is set.

File Status

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

// (16) The file is local off
LocalOff = 0x10
// (32) The file is local on and synchronized
Current = 0x20
// (64) A new version of the file is being uploaded
Uploading = 0x40
// (128) A new version of the file is being downloaded
Downloading = 0x80
// (256) The file is local on but not yet synchronized
Subscribed = 0x100
// (512) This file has not yet been posted to the server
Unposted = 0x200
// (1024) 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getFileList','boxPath':'box1/folder1'}"
{
  "status": "OK",
  "files" : [
      {
        "BoxName"    : "box1",
        "BoxPath"    : "box1/folder1/text.txt",
        "BoxUid"     : "zqdkecs1uw5bigdnoccrs4ngkuknsytj",
        "Executable" : 0,
        "FileName"   : "text.txt",
        "FilePart"   : "folder1/text.txt",
        "FileId"     : 41,
        "FolderId"   : 3,
        "ModDate"    : "2018-03-09 15:50:32",
        "Size"       : 27,
        "Status"     : 32
        "UtcModDate" : "2018-03-09 14:50:32",
        "VersionId"  : 53,
        "VersionTime": 1520603455175412,
      }
    ]
}

A recursive list looks something like this:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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",
              "FileId": 41,
              "FolderId": 16,
              "VersionId"  : 53,
              "VersionTime": 1520603455175412,
              "FileName": "text.txt",
              "Executable": 0,
              "FilePart": "folder1/text.txt",
              "Status": 32
            }
          ],
          "FileId": 16,
          "FolderId": 1,
          "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",
              "FileId": 42,
              "FolderId": 35,
              "VersionId"  : 45,
              "VersionTime": 1521041737357505,
              "FileName": "DSC_0570.JPG",
              "Executable": 0,
              "FilePart": "folder2/DSC_0570.JPG",
              "Status": 32
            }
          ],
          "FileId": 35,
          "FolderId": 1,
          "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",
          "FileId": 13,
          "FolderId": 1,
          "VersionId"  : 24,
          "VersionTime": 1492595845811938,
          "FileName": "text.txt",
          "Executable": 0,
          "FilePart": "text.txt",
          "Status": 32
        }
      ],
      "FileId": 1,
      "FileName": "box1",
      "FilePart": ""
    }
  ]
}

In general folders will lack the following fields: Executable, ModDate, Size, Status, UtcModDate, VersionId and VersionTime. 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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 regibox.manager.

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, boxUrl, 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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'getInvites', 'fields': ['boxName','uid']}"
{
  "status": "OK",
  "invites":[
    {"boxName": "box1","uid":"yes..."},
    {"boxName": "box2","uid":"jtp..."},
    ...
    {"boxName": "box50","uid":"ses..."}
  ],
  "hasMore": 1
}
When the query field is used, the results are not limited to 50. When in that case an error 59 is returned, it is likely that the server exceeded its request memory limit. In that case the query should be narrowed down or the requested fields reduced to a fitting result set.

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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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,
        "FolderId"   : 3,
        "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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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 in User Roles➤.

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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

// (1) This is a past version that is not locally kept
NonLocal = 0x1
// (2) The is the current version of the corresponding file
Current = 0x2
// (4) This is a past version that is locally available
LocalOn = 0x4
// (8) This version has the same parent as prior one
Conflict = 0x8
// (16) This version is being downloaded
Downloading = 0x10
// (32) The version is local on but not yet synchronized
Subscribed = 0x20
// (64) This version has not yet been posted to the server
Unposted = 0x40
// (128) 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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"        : "user@example.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"        : "user@example.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"        : "user@example.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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'invite', 'roleId':4, 'name':'John Sample','notes':'a test note', 'message':'Hello John\nhere is your invitation.', 'email':'user@example.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.exe doesn’t know which box:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'invite', 'roleId':4, 'name':'John Sample','notes':'a test note', 'message':'Hello John\nhere is your invitation.', 'email':'user@example.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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'invite', 'roleId':5, 'name':'John Sample','notes':'a test note', 'message':'Hello John\nhere is your invitation.', 'email':'user@example.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 filePart to the file or folder to turn on or off. In case of a folder, all files and folders below 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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. When this call returns, the log specified before it will have been flushed and closed.

This setting only applies to the running instance and does not persist past process restarts.
As of version 3.0 sensitive data is stripped from the logs in realtime.
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 level 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 see Controlling regiboxd➤ or run regiboxd.exe 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, DBUG 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 DBUG. If filePath is also omitted, logging is simply turned off.

DBUG was added in version 3.0.

This example call turns on verbose logging:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'logging','filePath':'C:/box-+D.log'}"
{
    "status": "OK",
    "logPath": "C:/box-2024-09-03.log"
}

The returned logPath is set when there is a current value and shows any given dynamic tokens like +P resolved to their current value.

logPath was added in version 3.0.

This is how to turn it off again:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'logging'}"
{"status": "OK"}
Making logging calls while diagnostics➤ is enabled, produces unspecified results.

newBox

Creates a new regibox on the given regiboxd.exe 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newBox','name':'con'}"
{
  "status": "ERROR",
  "eMsg"  : "The file name '<file>' is invalid. Please choose another name. Avoid special characters (/?\\<>:*|\") and 'lptN', 'comN', 'con', 'nul' or 'prn'.",
  "desc"  : "con",
  "ec"    : 328
}

Also worth noting are already existing box folders:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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.exe instance with potential validation. This function is equivalent to a set of setConfig➤ calls with regify and/or SMTP validation.

Key Example value Type Description

op

newConfig

string

Description of the desired operation.

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.

connectTimeout

8

integer

Number of seconds until a network connection attempt times out.

Added in version 3.0.

eventLogPath

c:/regibox/events.log

string

Optional, where to write important events to.

keepRemovedBoxes

0

integer

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

locale

en

string

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

maxFolderThreads

3

integer

Optional maximum number of concurrent threads to upload folder changes. Default is 5.

networkMode

239

integer

Optional, when the box root does not get file access monitoring events, such as on a network share. The codes are described in Network Mode➤ Default is 0.

In version 3.0 enableNetworkMode was removed and rolled into this field as mode None = 239.

providerUrl

https://regify.provider.com

string

The URL to the regify provider. Triggers regify account validation.

proxyPacFile

http://pachost/pac

string

Optional file path or URL to PAC file to use. Unsets proxyServer.

In version 3.0 proxySelection was removed and is now determined by either setting proxyPacFile, proxyServer or neither.

proxyPass

mysecret

string

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

proxyServer

myproxy:3128

string

Optional static address of proxy server, Unsets proxyPacFile.

proxyUser

user

string

Optional user account for the proxy when it is enabled.

regifyPass

mysecret

string

The password for the regify account. Triggers regify account validation.

regifyUser

user@example.com

string

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

replyTo

user@example.com

string

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

smtpCopyMe

0

integer

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

smtpIgnoreSslError

0

integer

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

smtpPass

mysecret

string

Optional password to along with the smtpUser field.

smtpPort

25

integer

Optional port of the SMTP server. Default is 25.

smtpSender

user@example.com

string

Address the appears in the from header of a sent invitation, used when SMTP is enabled. Triggers SMTP validation when set with smtpServer.

smtpServer

mail.domain.com

string

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

smtpTlsUse

1

integer

Optional, whether and how to use TLS. Default is 0. The codes are described in TLS Use➤.

In version 3.0 smtpUseTls was removed and maps to either Tls = 2 or StartTls = 3.

smtpUser

user@example.com

string

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

speedDownload

0

integer

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

speedUpload

0

integer

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

Network Mode

The networkMode field contains a number with the following meaning:

// Disable  polling.
None = 239
// Slow  polling factor.
Lazy = 240
// Standard  polling factor.
Standard = 241
// Faster  polling factor.
Aggressive = 242

TLS Use

The smtpTlsUse field contains a number with the following meaning:

// TLS use is determined by port.
// 465 = RGB_tls_Tls, 587 = RGB_tls_StartTls and
// everything else RGB_tls_None.
Default = 0
// Use SMTP in the clear.
None = 1
// Use SMTP over TLS.
Tls = 2
// Start with plain SMTP and upgrade via STARTTLS.
StartTls = 3

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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'boxRoot':'/regibox/root/', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.com', 'regifyPass':'mysecret'}"
{
  "status": "OK"
}

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

Now we’ll try some SMTP settings:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'boxRoot':'/regibox/root/', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.com', 'regifyPass':'mysecret','smtpServer':'smtp.regify.com','smtpSender':'user@example.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.

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.com', 'regifyPass':'mysecret','smtpServer':'smtp.regify.com', 'smtpSender':'user@example.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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'newConfig', 'providerUrl':'https://regify.provider.com','regifyUser':'user@example.com', 'regifyPass':'mysecret','smtpServer':'smtp.regify.com', 'smtpSender':'user@example.com','smtpIgnoreSslError':1, 'smtpUser':'user@example.com','smtpPass':'mysmtpsecret'}"
{
  "status": "OK"
}

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

purgeFile

This function empties the given file out of the recovery bin of a given regibox. This action is irreversible.

Key Example value Type Description

op

purgeFile

string

Permanently delete given file from the recovery bin of a regibox.

uid

3xo…​

string

The uid of the box of which the file belongs to.

fileId

21

integer

The file id of the file to purge. Can be obtained via getRecoverList➤.

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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'purgeFile', 'uid':'3xo79f915967u3doyd8o7orfikjyn5d8','fileId':21}"
{
  "status": "OK"
}
purgeFile was added in version 3.0.

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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'resetConfig','keepLocal':1}"
{
  "status": "OK"
}

restoreFile

This function is similar to recoverVersion➤ except 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'restoreFile','fileId':4}"
{
  "status": "OK"
}

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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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 pressing Manage regiboxes in the regibox manager:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'resubscribeBox', 'uid':'3xogaxj3pctns7jig449gwnysx5pypgo','name':'new box1'}"
{
  "status": "OK"
}

Now we succeed. Let’s try it again:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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://regify.provider.com

string

The optional RGB_maxFolderThreadMaxnew value of the setting. Leave unset to blank setting.

A successful run looks like this:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'setConfig','setting':'providerUrl', 'value':'https://regify.provider.com'}"
{
  "status": "OK"
}

A failing call like this:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'setConfig','setting':'provider', 'value':'https://regify.provider.com'}"
{
  "status": "ERROR",
  "eMsg"  : "Invalid parameter.",
  "desc"  : "couldn't set field",
  "ec"    : 77
}

setUser

This function 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 a User Roles➤ integer while everything else expects a string. When this field is empty, name, notes or meta will be blanked.

User Roles

This field contains a number with the following meaning:

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

A sample call looks like this:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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. Whereas a not found users exhibit error 60 which technically speaking is file not found:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'setUser','uid':'zqdkecs1uw5bigdnoccrs4ngkuknsytj', 'email':'user@example.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".

unsubscribeBox

This is called to stop keeping a regibox locally without deleting or unfollowing it. Check deleteBox➤ for an explanation of the difference.

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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'unsubscribeBox', 'uid':'3xogaxj3pctns7jig449gwnysx5pypgo'}"
{
  "status": "OK"
}

A repeated call will fail as follows:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'unsubscribeBox', 'uid':'3xogaxj3pctns7jig449gwnysx5pypgo'}"
{
  "status": "ERROR",
  "eMsg"  : "The regibox could not be found.",
  "desc"  : "failed unsubscribing box",
  "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 filePart 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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'zapPast', 'uid':'srp79f915967u3doyd8o7orfikjyn5d','filePart':'bar'}"
{
  "status": "ERROR",
  "eMsg"  : "The regibox could not be found.",
  "desc"  : "failed deleting past versions of file",
  "ec"    : 48
}

It tells us. Next, the filePart is invalid:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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:

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -p -J "{'op':'zapPast', 'uid':'srp79f915967u3doyd8o7orfikjyn5d8','filePart':'foo'}"
{
  "status": "OK"
}

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

C:\> "C:\Program Files\regiboxd\regiboxctl.exe" -c "C:\regibox\config" -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
}