{"id":5177,"date":"2026-11-18T21:22:06","date_gmt":"2026-11-18T21:22:06","guid":{"rendered":"https:\/\/bitflow-solutions.com\/guias-tecnicas\/tibco-activespaces-5-2-admin-commands\/"},"modified":"2026-11-18T21:22:06","modified_gmt":"2026-11-18T21:22:06","slug":"tibco-activespaces-5-2-admin-commands","status":"publish","type":"bf_guia","link":"https:\/\/bitflow-solutions.com\/en\/guias-tecnicas\/tibco-activespaces-5-2-admin-commands\/","title":{"rendered":"TIBCO ActiveSpaces 5.2: basic administration commands"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">A practical cheat sheet with the <strong>administration commands for TIBCO ActiveSpaces 5.2<\/strong>: the realm service on FTL servers, defining the grid with <code>tibdg<\/code>, starting the processes, status, scaling, checkpoints and logs. All the commands have been checked against the official administration manual for version 5.2, and you also have them in the <strong>README.md<\/strong> on the left.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What you\u2019ll learn<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The components of ActiveSpaces 5.2 and what changed from 4.x: the realm service is now FTL servers.<\/li>\n\n\n<li>Connecting <code>tibdg<\/code> to the realm and defining a complete grid with a script.<\/li>\n\n\n<li>Creating tables, columns and indexes, and starting the processes in the right order.<\/li>\n\n\n<li>Checking the grid status, scaling it with copysets and distributing clients across proxies.<\/li>\n\n\n<li>Taking checkpoints, restoring from them and knowing where the logs and metrics are.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Prerequisites<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>TIBCO ActiveSpaces 5.2<\/strong> installed, with its licence or activation service.<\/li>\n\n\n<li><strong>TIBCO FTL 7.2 or later<\/strong> for the realm service.<\/li>\n\n\n<li>Terminal access (bash) to the grid machines and to the FTL server URL.<\/li>\n\n\n<li>Familiarity with the basic concepts of a data grid: tables, keys, replicas and quorum.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Step by step<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. Understand the components<\/h3>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Component<\/th><th>What it does<\/th><\/tr><\/thead><tbody><tr><td><strong>Realm service<\/strong> (FTL servers)<\/td><td>Stores the grid configuration and coordinates everything else. In 5.x it is a cluster of TIBCO FTL servers (<code>tibftlserver<\/code>): 1 in development, 3, 5 or 7 in production. There is no longer a separate realm server.<\/td><\/tr><tr><td><strong>State keepers<\/strong> (<code>tibdgkeeper<\/code>)<\/td><td>Keep track of the grid state (which node is primary in each copyset). In production, 3 on different machines: the grid works as long as there is quorum (2 out of 3).<\/td><\/tr><tr><td><strong>Nodes<\/strong> (<code>tibdgnode<\/code>)<\/td><td>Store the data in memory and on disk. They are grouped into <strong>copysets<\/strong>: each copyset stores a part of the data, replicated across its nodes (2 per copyset in production).<\/td><\/tr><tr><td><strong>Proxies<\/strong> (<code>tibdgproxy<\/code>)<\/td><td>Receive connections from applications and route them to the node that holds each piece of data.<\/td><\/tr><tr><td><strong>Administration service<\/strong> (<code>tibdgadmind<\/code>)<\/td><td>Required for SQL definition operations (for example, <code>DROP TABLE<\/code>). Running it as a service inside the FTL server is recommended.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">For production, the minimum recommended configuration is: 3 state keepers on different machines and 2 nodes per copyset.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">2. Start the realm service<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Start the FTL servers before any other component:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># A single FTL server (development)\ntibftlserver -n ftl1@host1:8080 --license https:\/\/activation.company.local:7070\n\n# Cluster of FTL servers (production: 3, 5 or 7), each one with the same YAML\ntibftlserver -c ftl-cluster.yaml -n ftl1 --license https:\/\/activation.company.local:7070<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">3. Connect tibdg to the realm<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\"><code>tibdg<\/code> is the administration tool. Its general syntax is <code>tibdg [-r realm_url] [-g grid] [-s script] [-m message] command arguments<\/code>. If you don\u2019t specify <code>-g<\/code>, it works on the <code>_default<\/code> grid.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># The realm service URL is given with -r (default http:\/\/localhost:8080)\ntibdg -r http:\/\/ftl1:8080 status\n\n# With a cluster of FTL servers, the URLs separated by |\ntibdg -r \"http:\/\/ftl1:8080|http:\/\/ftl2:8080|http:\/\/ftl3:8080\" status\n\n# Or just once, in an environment variable\nexport TIBDG_FTL=\"http:\/\/ftl1:8080|http:\/\/ftl2:8080|http:\/\/ftl3:8080\"\ntibdg -g mygrid status\n\n# Help for any command\ntibdg help\ntibdg help grid create\ntibdg help table<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">With security enabled, the credentials go in <code>TIBDG_FTL_USER<\/code>, <code>TIBDG_FTL_PASSWD<\/code> and <code>TIBDG_FTL_TRUSTFILE<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">4. Define the grid with a script<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Save the definition in a file (<code>mygrid.tibdg<\/code>) so you can repeat it in every environment: the grid, its copyset, the nodes, the state keepers and the proxies, with automatic checkpoints every 10 minutes and the last 5 kept.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>grid create statekeeper_count=3 copyset_size=2 checkpoint_interval=600 checkpoint_retention_limit=5 mygrid\ncopyset create cs1\nnode create --copyset cs1 --dir .\/n1_data n1\nnode create --copyset cs1 --dir .\/n2_data n2\nkeeper create --dir .\/k1_data k1\nkeeper create --dir .\/k2_data k2\nkeeper create --dir .\/k3_data k3\nproxy create p1\nproxy create p2<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">And apply it in one go, with a message that is kept in the deployment history:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdg -r http:\/\/ftl1:8080 -g mygrid -s mygrid.tibdg -m \"Initial grid definition\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If you prefer to be prompted step by step, <code>tibdg grid generate mygrid.tibdg<\/code> generates the script interactively.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">5. Create tables, columns and indexes<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Each table is created with its key and then columns are added (types: <code>long<\/code>, <code>double<\/code>, <code>string<\/code>, <code>datetime<\/code>, <code>opaque<\/code> and, in 5.2, <code>vector_float32[dim]<\/code>). Indexes only support <code>long<\/code> or <code>string<\/code> columns.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdg -g mygrid table create default_ttl=0 orders id long\ntibdg -g mygrid column create orders customer string\ntibdg -g mygrid column create orders amount double\ntibdg -g mygrid column create orders created datetime\ntibdg -g mygrid index create orders idx_customer customer\ntibdg -g mygrid table list<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">6. Start the processes in order<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Always <strong>state keepers, then nodes, then proxies<\/strong>. The options <code>-k<\/code> (log file prefix), <code>-q<\/code> (maximum size in bytes) and <code>-w<\/code> (number of files kept) control log rotation.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># 1. State keepers (all three; the grid needs quorum: at least 2)\ntibdgkeeper -n k1 -r http:\/\/ftl1:8080 -g mygrid -k \/var\/log\/as\/k1 -q 10485760 -w 5\ntibdgkeeper -n k2 -r http:\/\/ftl1:8080 -g mygrid -k \/var\/log\/as\/k2 -q 10485760 -w 5\ntibdgkeeper -n k3 -r http:\/\/ftl1:8080 -g mygrid -k \/var\/log\/as\/k3 -q 10485760 -w 5\n\n# 2. Nodes, one at a time: wait for each one to be synchronised before the next\ntibdgnode -n n1 -r http:\/\/ftl1:8080 -g mygrid -k \/var\/log\/as\/n1\ntibdgnode -n n2 -r http:\/\/ftl1:8080 -g mygrid -k \/var\/log\/as\/n2\n\n# 3. Proxies (with -e if clients reach them through another address)\ntibdgproxy -n p1 -r http:\/\/ftl1:8080 -g mygrid -e proxy1.company.local:8888\ntibdgproxy -n p2 -r http:\/\/ftl1:8080 -g mygrid -e proxy2.company.local:8888<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">7. Check the grid status<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\"><code>tibdg status<\/code> is the first command whenever in doubt: it shows the processes and the estimated size of each node, plus a reindexing section when an index is being built.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdg -g mygrid status               # processes (nodes, keepers, proxies) and estimated size\ntibdg -g mygrid node status n1       # details of one process\ntibdg -g mygrid table list           # defined tables\ntibdg -g mygrid copyset list         # copysets\ntibdg -g mygrid proxy clients p1     # clients connected to a proxy<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">8. Scale the grid with copysets<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Capacity grows by adding copysets. After starting the new nodes, <code>grid redistribute<\/code> redistributes the data; to scale down, deactivate the copyset, redistribute and remove it:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># Add capacity: a new copyset with its two nodes\ntibdg -g mygrid copyset create cs2\ntibdg -g mygrid node create --copyset cs2 --dir .\/n3_data n3\ntibdg -g mygrid node create --copyset cs2 --dir .\/n4_data n4\n# ... start n3 and n4 with tibdgnode ...\ntibdg -g mygrid grid redistribute\ntibdg -g mygrid status               # follow the redistribution of the data\n\n# Remove capacity: empty the copyset, redistribute and remove it\ntibdg -g mygrid copyset deactivate cs2\ntibdg -g mygrid grid redistribute\ntibdg -g mygrid copyset remove cs2<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">9. Distribute clients across proxies<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">If one proxy is more loaded than the others, or before stopping it for maintenance, move its clients to other proxies without interrupting the service:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdg -g mygrid proxy clients p1                 # client connections of the proxy\ntibdg -g mygrid proxy shed p1 clients 10         # move 10 clients to other proxies\ntibdg -g mygrid proxy shed p1 connection 4711    # move a specific connection<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">10. Take checkpoints<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">A checkpoint is a consistent copy of the grid data. In addition to the automatic ones (step 4), take a manual one before any significant change:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdg -g mygrid checkpoint create before-the-upgrade\ntibdg -g mygrid checkpoint list                  # ID, name, directory, date and status\ntibdg -g mygrid checkpoint tables before-the-upgrade\ntibdg -g mygrid checkpoint validate before-the-upgrade\ntibdg -g mygrid checkpoint delete before-the-upgrade<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">11. Restore from a checkpoint<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Restoring takes the whole grid back to the moment of the checkpoint:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># 1. Load the grid definition saved with the checkpoint\ntibdg -g mygrid -r http:\/\/ftl1:8080 grid load -rollback realmserver-grid.json\n\n# 2. Mark the checkpoint you are going back to\ntibdg -g mygrid rollback create 12\n\n# 3. Restore each node's data directory from checkpoints\/&lt;date&gt;_..._chkpt and start it\n\n# 4. When finished, remove the rollback mark\ntibdg -g mygrid -r http:\/\/ftl1:8080 rollback delete<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">12. Check logs and metrics<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>If the processes run as services inside the FTL server, each one can have its own <code>logfile<\/code> in the YAML; otherwise, their output goes to the FTL server log, prefixed with the component name.<\/li>\n\n\n<li>If they run separately, each one\u2019s log is the one you specified with <code>-k<\/code>.<\/li>\n\n\n<li>The FTL server collects the metrics from the ActiveSpaces processes and exposes them for <strong>Prometheus<\/strong> to scrape.<\/li>\n\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">And the administration service, if you run it separately, with its own log and trace level (<code>severe<\/code>, <code>warn<\/code>, <code>info<\/code> or <code>debug<\/code>):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tibdgadmind -r http:\/\/ftl1:8080 -l http:\/\/0.0.0.0:7171 --logfile \/var\/log\/as\/admind --max-log-size 10485760 --max-logs 5 --trace warn<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Common errors<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">tibdg cannot find the grid or the realm<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Without <code>-r<\/code> or <code>TIBDG_FTL<\/code>, <code>tibdg<\/code> connects to <code>http:\/\/localhost:8080<\/code>; without <code>-g<\/code>, it uses the <code>_default<\/code> grid. Always specify them, especially if you manage several environments from the same machine.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The grid stops responding when a state keeper goes down<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">With 3 state keepers, quorum is required (2 running). If only one is left, the grid cannot work: start another one and spread them across different machines so that a single failure cannot take down two.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Nodes are slow or fail to synchronise at startup<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Start them one at a time and wait for each node to finish synchronising (<code>tibdg status<\/code>) before starting the next one.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u201cgrid redistribute\u201d does not move data to the new copyset<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The nodes of the new copyset must be running before you redistribute. Check with <code>tibdg status<\/code> that they appear as running.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">There is no tibdg command to drop a table<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Tables are dropped with SQL (<code>DROP TABLE<\/code>) from the API, and for that the administration service must be running (<code>tibdgadmind<\/code> or the service inside the FTL server). <code>tibdg table purge<\/code> only cleans up tables that have already been dropped.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Error when creating an index<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The columns of an index must be of type <code>long<\/code> or <code>string<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Unexpected behaviour after upgrading from 4.x<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">ActiveSpaces 5.2 requires FTL 7.2 or later and no longer uses its own realm server. Check the version of the FTL servers and the release notes before upgrading.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Next steps<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Enable FTL 7 security: your own certificates, mTLS and OAuth2.<\/li>\n\n\n<li>Configure forwarding between 5.2 grids for disaster recovery.<\/li>\n\n\n<li>Send the FTL server metrics to Prometheus and Grafana, with alerts on quorum and node disk space.<\/li>\n\n\n<li>Version the <code>tibdg<\/code> scripts and apply them from a pipeline in each environment.<\/li>\n\n<\/ul>\n\n\n","protected":false},"excerpt":{"rendered":"<p>The day-to-day commands in TIBCO ActiveSpaces 5.2: realm service on FTL servers, tibdg, grid definition, tables, starting processes, status, scaling with copysets, checkpoints and logs.<\/p>\n","protected":false},"featured_media":0,"template":"","bf_tecnologia":[102,106],"bf_nivel":[109],"class_list":["post-5177","bf_guia","type-bf_guia","status-publish","hentry","bf_tecnologia-integration","bf_tecnologia-monitoring","bf_nivel-intermediate"],"acf":[],"_links":{"self":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5177","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia"}],"about":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/types\/bf_guia"}],"version-history":[{"count":0,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5177\/revisions"}],"wp:attachment":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/media?parent=5177"}],"wp:term":[{"taxonomy":"bf_tecnologia","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_tecnologia?post=5177"},{"taxonomy":"bf_nivel","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_nivel?post=5177"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}