Regiboxd first steps

From regify WIKI
Jump to navigation Jump to search

Creating your first regibox on Windows

  1. After you downloaded the installer, please run and finish the setup.
  2. 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.
  3. Go to the root folder of your drive:
    cd c:\
  4. Create a directory as your instance folder. It will hold your future regibox configuration:
    mkdir c:\rgbx_config
  5. Create a root folder as root for your regiboxd regiboxes:
    mkdir c:\rgbx_root
    • IMPORTANT: Do not use the same folder for configuration and data!
  6. Register your regiboxd as service:
    regiboxd -c "c:\rgbx_config" -r "c:\rgbx_root" -i "MyExampleRegibox"
    • 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 regibox as service with the name MyExampleRegibox.
    • If you don't get Service MyExampleRegibox has been successfully installed, ensure that you run the commandline with administrator permissions.
  7. Validate the service by listing all regiboxd services:
    regiboxd -L
    Currently installed regiboxd service instances. Name(pid) means running, Command line
    MyExampleRegibox (984) "C:\Program Files\regiboxd\regiboxd.exe" -I "regiboxd_MyExampleRegibox" -c "c:\rgbx_config"
  8. Configure your new regibox service with your credentials.
    • Technically, regiboxd is controlled by placing a json file request.tmp into the configuration subfolder req\. Then, the result is placed in a file response.tmp in the res\ folder.
    • It is more easy to control regiboxd using the regiboxctl tool, which takes care of placing the file and observing the result.
    • Note that we use an uppercase -J to provide Windows specific json (see regiboxd manual).
    • regiboxctl -c "c:\rgbx_config" -p -J "{'op':'newConfig', 'providerUrl':'https://yourProviderDomain.com', 'regifyUser':'user@company.com', 'regifyPass':'password'}"
    • You should get some json result showing { "status": "OK" }. If you get an error, validate your request.
  9. Create your first regibox like this:
    regiboxctl -c "c:\rgbx_config" -J "{'op':'newBox', 'name':'box1'}"
    { "status": "OK", "uid" : "xksiypdqycmd7dhr6s8tbyqx8qsdcfnw" }
    • You should get some 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.


Congratulations, you have just created your first regibox.

Uninstall a regiboxd service

In order to unregisters a regiboxd service, call regiboxd with the -u option:

regiboxd -u "MyExampleRegibox"

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:

regiboxd -c "c:\rgbx_config" -i "MyExampleRegibox"

NOTE:
If a config is already existing, you can omit the -r setting like in this example call.

NOTE:
This unregisters and re-register is also what you should do before updating regiboxd to a new version. Unregister all running regiboxd instances, update your software and re-register the services.

NOTE:
Sometimes you need to start the regiboxd service manually after it was unregistered and re-registered. Use Windows Service management for this. You can also try net start MyExampleRegibox.

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:

regiboxctl -c "c:\rgbx_config" -J "{'op':'diagnostics'}"
{"status":"OK","desc":"diagnostics started"}

To stop it, run the same again

regiboxctl -c "c:\rgbx_config" -J "{'op':'diagnostics'}" -t 60
{"status":"OK","desc":"Diagnostics written to c:/rgbx_config/lib/tmp/regibox-diagnostics.zip"}

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:

regiboxctl -c "c:\rgbx_config" -J "{'op':'logging', 'filePath':'c:\\temp\\box.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:

regiboxctl -c "c:\rgbx_config" -J "{'op':'logging'}"