I’ve been using the Essbase CLI ever since it was released with Essbase Cloud in 2017 and although I’d read all the docs, used the CLI to automate tasks, and even given presentations on it, exactly how authentication worked with it always seemed a bit obscure to me. In a very simple workflow, I might call the CLI and then use it to list applications on my server, like this (commands entered are in bold):

tim$ ./esscs.sh login -essbaseurlhttps://myserver/essbase-user myuser -password mypassword
user "myuser" logged in with "Service Administrator" role
Essbase version = 21.3.2.0.0, build = 023
Essbase Command Line Interface version = 21.3.2.0.0, build = 023
tim$ ./esscs.sh listapp
Sample
Demo
MyApp

The thing that always puzzled me is that — unlike, say, MaxL, where once you start a session you are “inside” the tool until you exit — after each Essbase CLI operation you are simply back at the command prompt. So how does the CLI know about my session / login when I go to issue that listapp command?

And what about the setpassword command, that lets me do this (commands entered are in bold)…

tim$ ./esscs.sh setpassword -essbaseurl https://myserver/essbase -user myuser
Enter password:
User credentials stored successfully
tim$ ./esscs.sh login -essbaseurl https://myserver/essbase -user myuser
user “myuser" logged in with "Service Administrator" role
Essbase version = 21.3.2.0.0, build = 023
Essbase Command Line Interface version = 21.3.2.0.0, build = 023

Notice that I didn’t have to supply a password in order to log in this time. A major advantage here is that the password does not have to appear in plaintext in either a script or associated log files, and if the password needs to be changed it can be done once with setpassword in one place. The setpassword documentation simply says that a password is “stored” but doesn’t explain how or where, which is something I’m interested to know partly from curiosity and partly because in a real system I would like to understand who else might be able to make use of those credentials. Fortunately, while the docs themselves don’t explain any further therearehints in the client-side CLI logs, and there is also a support doc (Doc ID 2806943.1) that talks about some problems with this feature when running concurrent CLI sessions and gives a lot more detail about what’s going on behind the scenes.

The first thing to know is that by default the CLI is creating a subdirectory in USER_HOME – what exactly that means varies depending on platform, but on my Mac OS X examples above, it’s in /users/tim/ and it’s called .esscs (a period at the start of a name effectively hides a file or directory on Unix-like platforms, and you have to, for example, use the switch -A to make the them show up when you list directory contents with the ls command). What we find inside that directory looks like this:

tim$ ls -lA
total 32
-rw-------  1 tim  staff   848 Feb  1 12:30 .cli
-rw-r--r--  1 tim  staff  6973 Feb  1 11:44 .cli_cert
-rw-r--r--  1 tim  staff  1329 Feb  1 12:30 .cli_p12

Three files, themselves also ‘hidden’ with a period at the start of the name. These files are mostly unreadable / encrypted and all three are created the moment you log in. From what little is readable (and the clue in the name), .cli_cert contains information about the certificate used by your Essbase instance. .cli and .cli_p12 get bigger and smaller as you log in or out, or use setpassword or unsetpassword, and .cli_p12 appears to contain a Unix timestamp of both the time setpassword was used (if it was) and the last login. I’m sure someone more familiar with SSL etc would be able to be more specific about the contents, but the short story is that I don’t think there’s much that can usefully achieved by manipulating these files beyond knowing that they need to exist.

What I did want to check was whether they are inherently tied to a particular operating system user (since they exist under the USER_HOME directory). On my Mac I copied my .esscs directory over to an identical location in another user’s folders and found that I was able to log in using that operating system user too. Not too much of surprise, but this tells me that access to these files does effectively grant “portable” access to Essbase, so exercise appropriate caution in who can read them, or see backup copies of them etc. The situation is similar to MaxL using encrypted credentials in that having both the private key parameter and an associated MaxL script will let you access Essbase – although you won’t be able to see the password itself directly.

The support doc (Doc ID 2806943.1) mentioned above discusses concurrency issues where multiple sessions or scripts might trigger actions that need to update these files at the same time. We ran into this problem at a client, which is why I was running a search that led me to that document in the first place. The recommendations to avoid those issues are twofold: First, upgrade the CLI to at least 21.2, which is probably already the case for any recent install. Second, you can set ESSCLI_CACHE_DIR as an environment variable to specify a distinct location for the cached files used by different tasks / sessions to avoid conflict. If the CLI session finds ESSCLI_CACHE_DIR is set, it will use that value rather than defaulting to USER_HOME/.esscs. It would be (conservative) good practice to set that value to something unique to each script / task when building CLI scripts to protect against any concurrency issues.