Create a new config file

Execute machbase-neo with gen-config and save its output as default config file

machbase-neo gen-config > ./machbase-neo.conf

Edit generated config so that customize settings, then start machbase-neo with --config <path> or -c <path> option to direct where machbase-neo read config.

machbase-neo serve --config ./machbase-neo.conf

Database directory

The default value of DataDir is ${execDir()}/machbase_home which is a sub-directory of where machbase-neo executable file is.

Change it to new path where you want to store the database files. If the folder is new and has no database files, machbase-neo will create a new database automatically.

Preference directory

The default value of PrefDir is prefDir("machbase") which is $HOME/.config/machbase.


SSH ShellShell.Listenerstcp://
Machbase nativeMachbase.PORT_NO5656
Machbase native port 5656 is used for native clients such as JDBC and ODBC. JDBC, ODBC drivers can be found from Machbase home page.

Config References

Syntax of config file adopts the HCL syntax.


Several functions are supported for the value of config item.

  • flag(A, B) : Get value of command line flag ‘A’. if not specified, apply B as default value.
  • env(A, B) : get value of Environment variable ‘A’. if not specified, apply B as default value
  • execDir() : Get directory path where executable file is.
  • userDir() : Get user’s home directory, On Linux and macOS, it returns the $HOME environment variable.
  • prefDir(subdir) : Ger user’s preference directory, On Linux and macOS, it returns the real path of $HOME/.config/{subdir}
Combine env() and flag()
It is general practice for seeking user’s setting that check command line flag first then find Environment variable and finally apply default value if both are not specified. We can write value flag("--my-var", env("MY_VAR", "myvalue")) for this use case

define DEF

This section is for the default values. the variables in this section are referred in other section. Users can define their own variables and even change the command line flags. As example below, LISTEN_HOST is taken value from --host flag of command line, but take "" as default if --host flag is not provided.

If change "" to "", the default value will be changed.

If change "--host" to "--bind" for example, command line flag will be changed. From then you can use machbase-neo serve --bind <ip_addr> instead of machbase-neo serve --host <ip_addr>.

define DEF {
    LISTEN_HOST       = flag("--host", "")
    SHELL_PORT        = flag("--shell-port", "5652")
    MQTT_PORT         = flag("--mqtt-port", "5653")
    HTTP_PORT         = flag("--http-port", "5654")
    GRPC_PORT         = flag("--grpc-port", "5655")
    GRPC_SOCK         = flag("--grpc-sock", "${execDir()}/mach-grpc.sock")
    MACH_PORT         = flag("--mach-port", "5656")

define VARS

This section defines commonly used variables.

define VARS {
    PREF_DIR              = flag("--pref", prefDir("machbase"))
    DATA_DIR              = flag("--data", "${execDir()}/machbase_home")
    FILE_DIR              = flag("--file", "${execDir()}")
    UI_DIR                = flag("--ui", "")
    MACH_LISTEN_HOST      = flag("--mach-listen-host", DEF_LISTEN_HOST)
    MACH_LISTEN_PORT      = flag("--mach-listen-port", DEF_MACH_PORT)
    SHELL_LISTEN_HOST     = flag("--shell-listen-host", DEF_LISTEN_HOST)
    SHELL_LISTEN_PORT     = flag("--shell-listen-port", DEF_SHELL_PORT)
    GRPC_LISTEN_HOST      = flag("--grpc-listen-host", DEF_LISTEN_HOST)
    GRPC_LISTEN_PORT      = flag("--grpc-listen-port", DEF_GRPC_PORT)
    GRPC_LISTEN_SOCK      = flag("--grpc-listen-sock", DEF_GRPC_SOCK)
    HTTP_LISTEN_HOST      = flag("--http-listen-host", DEF_LISTEN_HOST)
    HTTP_LISTEN_PORT      = flag("--http-listen-port", DEF_HTTP_PORT)
    MQTT_LISTEN_HOST      = flag("--mqtt-listen-host", DEF_LISTEN_HOST)
    MQTT_LISTEN_PORT      = flag("--mqtt-listen-port", DEF_MQTT_PORT)
    MQTT_MAXMESSAGE       = flag("--mqtt-max-message", 1048576) // 1MB

    HTTP_ENABLE_TOKENAUTH = flag("--http-enable-token-auth", false)
    MQTT_ENABLE_TOKENAUTH = flag("--mqtt-enable-token-auth", false)
    MQTT_ENABLE_TLS       = flag("--mqtt-enable-tls", false)

    HTTP_ENABLE_WEBUI     = flag("--http-enable-web", true)
    HTTP_DEBUG_MODE       = flag("--http-debug", false)

    EXPERIMENT_MODE       = flag("--experiment", false)

    MACHBASE_ENABLE_SIGHANDLER = flag("--machbase-enable-sighandler", false)
    MACHBASE_INIT_OPTION       = flag("--machbase-init-option", 2)

    CREATEDB_SCRIPT_FILES  = flag("--createdb-script-files", "")

logging config

Consoleboolprint out log message on console
Filenamestringlog file path - for stdout, ex) /logs/machbase-neo.log
DefaultPrefixWidthintalignment width of log prefix
DefaultEnableSourceLocationboolenable logging source filename and line number
Levelsarrayarray of Level object
Appendboolappend log file, if it exists
RotateSchedulestringschedule to rotate log file ex) “@midnight”
MaxSizeintmax log file size in MB
MaxBackupsintmax number of backup files
MaxAgeintmax days to keep the backup files
Compressboolcompress the backup files
UTCboolUse UTC time for logging
  • Level object
Patternstringglob pattern form logger’s name
Levelstringlog level for the logger
module "" {
    name = "neolog"
    config {
        Console                     = false
        Filename                    = flag("--log-filename", "-")
        Append                      = flag("--log-append", true)
        RotateSchedule              = flag("--log-rotate-schedule", "@midnight")
        MaxSize                     = flag("--log-max-size", 10)
        MaxBackups                  = flag("--log-max-backups", 1)
        MaxAge                      = flag("--log-max-age", 7)
        Compress                    = flag("--log-compress", false)
        UTC                         = flag("--log-time-utc", false)
        DefaultPrefixWidth          = 16
        DefaultEnableSourceLocation = flag("--log-source-location", false)
        DefaultLevel                = flag("--log-level", "INFO")
        Levels = [
            { Pattern="neo*", Level="TRACE" },
            { Pattern="http-log", Level="DEBUG" },

server config

This section is for the database server consists of multiple parts those will be explained in section by section.


MachbaseHomestringdirectory path where database files are stored


Machbase core properties are here, please refer Property section of Machbase Manual for details. And full manual for Machbase is here


This allows remote access machbase-neo shell via ssh. Since default LISTEN_HOST is "" the ssh access only available from same host machine. Set "" or exact IP address of host machine to allow remote access.

Before allow remote access, it is strongly recommended to change SYS’s default password from manager to your own.
Listenersarray of stringlistening addresses (ex: tcp://, tcp://
IdleTimeoutdurationserver will close the ssh connection if there is no activity for the specified time


machbase-neo’s gRPC listening address and size limit of messages are configured.

Listenersarray of stringlistening addresses
MaxRecvMsgSizeintmaximum message size in MB that server can receive
MaxSendMsgSizeintmaximum message size in MB


server’s HTTP listener config.

Listenersarray of stringlistening addresses
EnableTokenAuthboolenable token based authentication (default false)
EnableWebUIboolenable web user interface (default true)


Listenersarray of stringlistening addresses
MaxMessageSizeLimitintmaximum size limit of payload in a PUBLISH
(default 1048576 = 1MB)
EnableTokenAuthboolenable token based authentication (default false)
EnableTlsboolenable TLS for the TCP listeners (default false)

neo-server config

module "" {
    name = "neosvr"
    config {
        PrefDir          = VARS_PREF_DIR
        DataDir          = VARS_DATA_DIR
        FileDirs         = [ VARS_FILE_DIR ]
        ExperimentMode   = VARS_EXPERIMENT_MODE
        CreateDBScriptFiles = [ VARS_CREATEDB_SCRIPT_FILES ]
        Machbase         = {
            HANDLE_LIMIT     = 2048
            PORT_NO          = VARS_MACH_LISTEN_PORT
        Shell = {
            Listeners        = [ "tcp://${VARS_SHELL_LISTEN_HOST}:${VARS_SHELL_LISTEN_PORT}" ]
            IdleTimeout      = "5m"
        Grpc = {
            Listeners        = [ 
            MaxRecvMsgSize   = 4
            MaxSendMsgSize   = 4
        Http = {
            Listeners        = [ "tcp://${VARS_HTTP_LISTEN_HOST}:${VARS_HTTP_LISTEN_PORT}" ]
            WebDir           = VARS_UI_DIR
            EnableTokenAuth  = VARS_HTTP_ENABLE_TOKENAUTH
            DebugMode        = VARS_HTTP_DEBUG_MODE
            EnableWebUI      = VARS_HTTP_ENABLE_WEBUI
        Mqtt = {
            Listeners           = [ "tcp://${VARS_MQTT_LISTEN_HOST}:${VARS_MQTT_LISTEN_PORT}"]
            EnableTokenAuth     = VARS_MQTT_ENABLE_TOKENAUTH
            EnableTls           = VARS_MQTT_ENABLE_TLS
            MaxMessageSizeLimit = VARS_MQTT_MAXMESSAGE
        Jwt = {
            AtDuration = flag("--jwt-at-expire", "5m")
            RtDuration = flag("--jwt-rt-expire", "60m")
        MachbaseInitOption       = VARS_MACHBASE_INIT_OPTION
        EnableMachbaseSigHandler = VARS_MACHBASE_ENABLE_SIGHANDLER
Last updated on