Return of Troubleshooting Kanaka


Kanaka Troubleshooting tips:

When last I visited the topic of Kanaka, it was all NetWare all the time. I had lots of things to say, that you can read about in these articles:


But I wrote those way back in 2006, probably before I was even seriously involved in IDM stuff, and how the times have changed. Now Kanaka runs on Windows (not the free version with OES) or OES Linux. It now processes Login Scripts and much more.

Much of the advice I gave in the NetWare days is relevant in terms of Universal Password, Native File Access general concepts, however some of the specific details have changed.

For example, the web interface to configure Kanaka is no longer via NoRM (Novell Remote Manager) but rather its own web interface, which defaults to port 3088 (unsecure) and 3089 (Over SSL).

Configuring file access for AFP or CIFS is no longer NLM based, but rather Linux processes probably handled through yast.

Recently I ran into an issue with Kanaka, and since I had not really looked at it since the NetWare days, I needed to learn a bunch of things fast. As long as I was relearning this stuff, I figured I should write it down, since in searching for the answer to my issue, I came across my old stuff on Google, and it helped remind me of stuff I used to know. I guess Google has become my external memory store. Write it down, so Google can help me find it next time I need it.

First off, there are three main directories for stuff of interest.

/opt/novell/kanaka/engine/  (For the bin and lib subdirs with the actual code)
/var/opt/novell/kanaka/engine/ (For the logs, and User index, storage list, etc)
/etc/opt/novell/kanaka/engine/ (For the configuration).

That kind of makes sense. The configuration is in the /etc directory structure. The executable files are in the /opt directory structure, and the stuff that changes often (logs, user list, client list (No, not the Elliot Spitzer kind of client), storage resources is in the /var directory structure.

The main process is novell-kanakaengined, which can be called via the /etc/init.d/novell-kanakaengined script, which is also available as the rcnovell-kanakaengined script that should be in your path. This is fairly typical for Linux processes. There is an actual executable that takes parameters, that is called by a script that takes parameters, and then there is a shortcut to that script.

My issue was silly. I did something dumb (in hindsight, at the time it did not occur to me). I was helping setup a second Kanaka server to transition over from the production server. There is even some steps in the documentation that nicely explain how to migrate from one Kanaka server to the other. I followed the instructions, which were pretty good, except that they said at the end, to stop the first server, to copy the salt.dat file, then uninstall it.

I of course started up the second server while the first was running. So why does it matter? I wish the docs had explained WHY it matter! Well the salt.dat file is XML that looks like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

As you can see, it has an <Account> node, which has a KanakaProxy.acme object referenced. Well each Kanaka server generates the password for that object. I assume the <Salt> node is somehow a secret used to generate a unique password for the object. I do not think it is the actual password, I think it is a key used to generate a password from.

So when I started up my second server, it reset the password on the shared object, and the first server (the production one, oops) stopped working. It reported an error, in the log file in the /var/opt/novell/kanaka/engine/log directory:

01 2013-08-01 14:29:29 -14400 3 0001 2548 2080 ML:  Failed to authenticate as the Proxy Account, Result = 185


Hmm, the proxy account cannot log in. That cannot be good. Ok, so how to fix it.

I was lucky enough to get awesome support out of the forums, where one of the support folk was really on the ball and answered my initial request in about 25 minutes! (Faster than I would have waited on hold for support, I imagine!) We had a bit of back and forth before the final answer. Now his first answer was interesting, but he misunderstood my question. Regardless, his answer was very helpful, and in fact is worth recording, because it helps address another difference between NetWare and Linux.

On NetWare, NLMs (NetWare Loadable Modules) had the ability to act as root or admin, or whatever you want to call it. They could attain full permissions since they did not run as a user, rather as a process on the server itself. Linux is very different and does not have such a model per se. Therefore the CIFS.NLM and AFP.NLM could get files on behalf of any object that asked properly, since they could see everything.

In the Linux world, the process needs to run as something, and then it may still need a proxy user to get rights. He misunderstood my issue of Proxy users, in the more common sense of a proxy for AFP or CIFS, not in the KanakaProxy case. One nice thing added in either OES2 SP3 or OES 11, I forget which, is the move to share the proxy user for CIFS, AFS, LUM, NetStorage, whatever else, as a common-proxy user. This was a lot easier as it is easier to manage one than 4, 5 or more accounts.

Thus his advice was something like this.
Proxy user password is stored on the object itself and in the casa credentials as seen under CASAcli -l

You can reset the password on the eDir object as you do with any other user object. You then have to change the password stored for the user in the casa credentials.

See CASAcli -h for help. The bottom reports the following:

KEYVALUE=<cn=admin,o=novell> CASAcli -s -n <MyCredential> -k CN
KEYVALUE=<password> CASAcli -s -n <MyCredential> -k Password

Therefore to set the password on a CASA stored credential, you can do something like:

KEYVALUE=mysecret CASAcli -s -n afp-casa -k Password

If you execute CASAcli -l you will see a user named afp-casa. Each service may have its own
casa store.

Thus he was able to explain how to reset the CIFS or AFP proxy passwords. Alas that was not my issue, and once I explained that, he quickly came up with the right answer. In hindsight, I should have thought to go look and find this myself.

This also relies on an understanding of how the Linux init scripts work.

As I noted above, there is a script rcnovell-kanakaengined that is really a short cut to /etc/init.d/novell-kanakaengined, which is a typical init script that takes parameters like, start, stop, status and so on.

It is the 'and so on' part that is key. Go look at that script or any init script and here is the key snippet from it!

Early on they define:


even earlier on they define the _companyFolder, _productFolder, etc since they sell a Condrey version and a Novell version, so this was a clever way to make their lives easier with variables.

But the key element is a case statement to handle possible values passed into this script. You can see the start, stop, restart, status elements that are pretty common in init scripts. But there is the magical talisman! The proxy-reset option!

# Service switches
case "$1" in
echo -n "Starting Novell Kanaka for Mac Engine "

## Start daemon with startproc(8). If this fails
## the return value is set appropriately by startproc.
/sbin/startproc -q $KANAKA_BIN $KANAKA_PARAMS

# Remember status and be verbose
rc_status -v

echo -n "Shutting down Novell Kanaka for Mac Engine "
## Stop daemon with killproc(8) and if this fails
## killproc sets the return value according to LSB.

/sbin/killproc -TERM -t15 $KANAKA_BIN

# Remember status and be verbose
rc_status -v

## Stop the service and regardless of whether it was
## running or not, start it again.
$0 stop
$0 start

# Remember status and be quiet

echo -n "Checking for service Novell Kanaka for Mac Engine "
## Check status with checkproc(8), if process is running
## checkproc will return with exit status 0.

# Return value is slightly different for the status command:
# 0 - service up and running
# 1 - service dead, but /var/run/ pid file exists
# 2 - service dead, but /var/lock/ lock file exists
# 3 - service not running (unused)
# 4 - service status unknown :-(
# 5--199 reserved (5--99 LSB, 100--149 distro, 150--199 appl.)

# NOTE: checkproc returns LSB compliant status values.
/sbin/checkproc $KANAKA_BIN
# NOTE: rc_status knows that we called this init script with
# "status" option and adapts its messages accordingly.
rc_status -v

# If the daemon is currently running, prompt for shutdown
# before going into the proxy-reset mode
/sbin/checkproc $KANAKA_BIN

# An exit code of "0" from checkproc means the specified service is running
if ${_running} -eq 0; then
echo "The Engine service must be stopped before resetting the proxy account"
echo -n "Shutdown Engine [Y/N]: "

while :
read -n 1 _response
case "${_response}" in
[yY]) echo; $0 stop; break ;;
[nN]) exit 0 ;;

local _username=
local _password=

echo "Enter a username and password. The username should be entered using"
echo "dotted FDN format and should have full rights to manage the configured"
echo "proxy account for Novell Kanaka for Mac."
read -p "Username: " _username
read -p "Password: " -s _password
echo "Enter the DNS name or IP address of an eDirectory server for this action."
echo "Hit [Enter] to select the default of the local hostname."
read -p "eDirectory Server [${_default_server}]: " _temp_server
if ${_temp_server} != ""; then

$KANAKA_BIN --force-proxy-reset --default-server:${_default_server} --username:${_username} --password:${_password}

# Restart the service if it was already running.
echo -n "(Re)start service? [Y/N]: "
while :
read -n 1 _response
case "${_response}" in
[yY]) echo; $0 start ${_options}; break ;;
[nN]) break ;;

# Call rc_status quietly

echo "Usage: $0 {start|stop|status|restart|proxy-reset}"
exit 1

There is more to the script, go take a look at your copy. I just excerpted the interesting part for this conversation.

If you read through the proxy-reset option, you will see it does a couple of things. Checks if it is running, stops the process if it is, (Warns you, and gives you a choice too, classy!), gets the username and password for an admin account, takes the current server hostname and lets you override it (Probably relevant in a clustering world) then it calls the main function, and finally restarts the process.

The main function here is:

$KANAKA_BIN --force-proxy-reset --default-server:${_default_server} --username:${_username} --password:${_password}

Well we saw KANAKA_BIN is the path to the executable, set earlier and then it passes in the parameters it needs.

So we see that the main Kanaka binary, /opt/novell/kanaka/engine/bin/novell-kanakaengined has a parameter --force-proxy-reset.

What this does is forces Kanaka to use the admin credentials to go do a password change in eDir and change the password it stores in its configuration.

But the next question of interest is, if there is this parameter to the binary, what other ones does it take? So that is easy. Try the --help option. That returns:

acmeSrv:/opt/novell/kanaka/engine/bin # ./novell-kanakaengined --help

The following command line switches are supported:


Installs the program as a native NT service.
Program terminates immediately after performing this task.

Use the "--instance-name" switch if installing a specific
instance of the service.


Uninstalls the program from the native NT service database.
Program terminates immediately after performing this task.

Use the "--instance-name" switch if uninstalling a specific
instance of the service.


Start the native NT service associated with the program.
Program terminates immediately after performing this task.

Use the "--instance-name" switch if starting a specific
instance of the service.


Stop the native NT service associated with the program.
Program terminates immediately after performing this task.

Use the "--instance-name" switch if stopping a specific
instance of the service.


The logging level must be a valid log_levels_t value from
log_level_fatal [1] thru log_level_debug [8] {or
log_level_developer [9]}. This value will override the value
for logging level that is obtained from the configuration file.

Use only with the "--daemon" switch.


The instance-name value must not have any spaces or punctuation
characters in it. Restrict the range of values to mixed case
alphanumerics [lower case on Linux].

Use with the "--daemon" switch or the "--svc-*" switches.


Forces the creation of the data and config directories in the
default location if they do not already exist.

Use with the "--daemon" switch or the "--svc-install"


Run the program's main loop and do normal application
processing. If this switch is missing, the program will not run
as normal. This switch cannot be specified in combination with
any of the "--svc-*" switches.

Use the "--instance-name" switch if running as a specific
instance of the application.


Attempt to extend the schema. Program terminates

If run on Linux in an eDir environment, the --username and
--password switches must be present with valid values to specify
an account to use to perform the password reset, and the
--default-server switch must be present with a valid value.


Attempt to reset the proxy account password. Program terminates

If run on Linux in an eDir environment, the --username and
--password switches must be present with valid values to specify
an account to use to perform the password reset, and the
--default-server switch must be present with a valid value.


The value must be a valid eDir "NDAP" object FDN in dotted
form. If the type information is omitted, default typing rules
will be used [e.g. "CN,OU,O"].


The password that is associated with the object name that was
provided with the --username switch. If the object has no
password, then use the switch without a value trailing after the


The value of <server> can be a fully qualified DNS host name or
an IP address that identifies the server to which a connection
is established when authenticating to eDirectory.


Run the program with the engine in "Not Accepting Client
Requests" mode initially.

--help or -?

Display command line switch help information for this program.

02 2013-08-01 20:30:16 0 2 0001 5513 7fb4288ce700 ML: Saved the Salt state information, bResult = 0.
02 2013-08-01 20:30:16 0 2 0001 5513 7fb4288ce700 ML: Completed saving state information, bOK = 0.

Hmm, that is a fair number of switches. Looks like you can force it to extend the schema on demand, force the proxy reset as was discovered already, set the log level, install or uninstall it as a service (when running on Windows).

This is one of the nice things about Linux. Often a fair bit of information is sitting there in your file system that you may not be aware of, but if you think to look, you can find out some interesting things.

Now one of the issues I ran into along the way is that I did not know what should be in the various files. I thought it would be handy to post the contents of mine (Names have been changed to protect the innocent of course)

First off the main config file. This is the one that the /opt/novell/kanaka/engine/bin/ file seems to mostly configure. Amusingly, if you read that script file, you will see it calls a Java program as the config utility. I suppose that makes it cross platform, which probably makes sense from a supportability perspective.


<?xml version="1.0" encoding="utf-8"?>
<NotAcceptingLoginsReason />
<SRServers />

You can see the basic host info, ports, proxy home dir, Admin group. Which is a bit more than the script sets, but also some of the stuff the Config Wizard sets up. The Index Search Objects lists off the containers it is configured to do contextless logins through.

Also there is a Logger session that is where the changes you make in the web interface are recorded.

When you first set up a basic Kanaka instance via the config script you get something like this:

<?xml version="1.0" encoding="utf-8"?>

Once you start mucking about you get the rest of the data fleshed out.

Then there are the .dat files, in the /var/opt/novell/kanaka/engine/data directory.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Name>John Smith</Name>

This file is where the licensed and active workstations are tracked. The web interface will let you disable these, I suppose to minimize license count, if needed.

I trimmed this down to one example to save on space, but you will have one <Client> node set for each workstation.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

This is basically reflecting the settings you configured in the web interface. The names are pretty obvious, and this is helpful mostly is showing you what a working set of values might be.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OSVERSION>Server Version: Novell NetWare 5.70.03[DS]; Product Version: 6.50.3; OS Version: 5.70.3; DS Revision: 1055178</OSVERSION>
<OSNAME>OS Vendor: Novell; OS Revison: NetWare 5.70.03; OS Revision Date: May 23, 2005; OS Copyright: (C) Copyright 1983-2005 Novell Inc. All Rights Reserved.</OSNAME>

The storage-resources.dat file is where the information about the various servers, and the volumes they have, and how you wish them exposed/translated for the Mac (CIFS or AFP) is stored. This looks a lot more complex than what the NetWare version used to do.

I am not 100% sure what most of the settings mean and are used for, but I excerpted a single server with a single SYS volume for a complete example.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Finally we have the userindex.dat, where after a dredge (I think it also has been called a census in the past) the list of users found is stored. As before, for the sake of space I excerpted it down to a single users, but expect every user found in the various containers you specified in the IndexSearchObjects nodes in the kanaka.conf file will be stored. So I left only a single user in my example, but there are obviously going to normally be a lot more for you. You will just have many more <Item> nodes.

I hope by examining the files, the scripts, and config files Kanaka uses, it will make troubleshooting your issues easier. If nothing else, it may mean you have an example of what the various files content's should look like, when things are working properly.


How To-Best Practice
Comment List