regiboxd Specification
- Introduction
- The daemon
- Controlling regiboxd
- General Notes
- Examples
- API Reference
- acceptInvite
- deleteBox
- diagnostics
- emptyRecovery
- getActivities
- getBoxInfo
- getConfig
- getFileList
- getInvites
- getMetrics
- getPastVersion
- getRecoveryList
- getResource
- getUserList
- getVersionList
- invite
- localOnOff
- logging
- newBox
- newConfig
- recoverVersion
- resetConfig
- restoreFile
- resubscribeBox
- setConfig
- setUser
- unsubscribeBox
- zapPast
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) |
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 |
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 |
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 |
level |
|
string |
Optional desired log level. One of |
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. |
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
}