Session management

⚠️

LUXminer sessions are not a security feature! They are just a easy way for multiple processes to "exclusively" coordinate changes of the miner configuration. It assumes all involved actors will behave in a reasonable fashion; since "bad" actors can still ruin the party for everyone else, this feature should not be seen as a security measure.

Certain luxminer-specific commands require a session to be able to run. A session is nothing more than a system-generated identification that is used to "block" multiple people (or scripts!) from concurrently changing important configuration on the miner.

The general idea is that you should create a session only when you need it, do all the commands that you require, and then drop the session so the next actor can act.

💡

Sessions are only ever required in commands that write or change miner configuration. If you are only ever querying miner information (for example, to display a custom UI or collect mining statistics) you won't ever need to run a command that requires a valid session.

Creating a session

To create a session, use the logon command:

$ echo '{"command": "logon"}' | nc $MINER_IP 4028 | jq
{
  "SESSION": [
    {
      "SessionID": "yJN2nlj1"
    }
  ],
  "STATUS": [
    {
      "Code": 316,
      "Description": "LUXminer 0.1.0-15436f7140",
      "Msg": "Session created",
      "STATUS": "S",
      "When": 1667917312
    }
  ],
  "id": 1
}

It returns a single value, SessionID, which you should pass as the first parameter for every command that requires a session (frequencyset, voltageset, etc.). As long as the session is valid, you should reuse the SessionID.

💡

Sessions expire automatically after one minute. This period is refreshed every time you use the session.

At max, only one session can exist at any given time, so you should always check the result of logon to ensure you actually managed to get a valid session. If it fails, consider aborting you process or (even better) reporting the problem to the user and waiting a bit to try again.

Discarding a session

When you're done with your session, you can discard it with the logoff command:

$ echo '{"command": "logoff", "parameter":"yJN2nlj1"}' | nc $MINER_IP 4028 | jq
{
  "STATUS": [
    {
      "Code": 317,
      "Description": "LUXminer 0.1.0-15436f7140",
      "Msg": "Session dropped",
      "STATUS": "S",
      "When": 1667918555
    }
  ],
  "id": 1
}

The session is dropped cleanly, and a subsequent logon call will return a new SessionID. Do note that logoff requires the session itself as the first parameter, so you don't accidentaly discard the session of a different user.

Another, more drastic alternative, is to use the kill command:

$ echo '{"command": "kill"}' | nc $MINER_IP 4028 | jq
{
  "SESSION": [
    {
      "SessionID": "VI2LCs8i"
    }
  ],
  "STATUS": [
    {
      "Code": 318,
      "Description": "LUXminer 0.1.0-15436f7140",
      "Msg": "Kill session",
      "STATUS": "S",
      "When": 1667918597
    }
  ],
  "id": 1
}

As you can see, the different is that it does not require you to inform the session; it just kills whathever session is the currently active one and returns the SessionID that was killed. This is a way to forcefully terminate a session, and as such, it will generate a warning in the miner log.

⚠️

As tempting as it looks, do not use the kill command unless you have a very good reason to do so, and even then, ask for the user permission to do so, if applicable.Killing a session because it belongs to a buggy script that can cause harm to your units is a good reason, while killing just because "my script is super important and I want to execute this righ now, real quick" is not.

The rationale is that if everyone just start "killing" the current session according to its own needsno process or automated script would ever have a chance to complete successfully. As always, evaluate your scenario and make a judgement call based on your needs.

Checking for an existing session

You can get the SessionID of the current active session, if any, by using the session command:

$ echo '{"command": "session"}' | nc $MINER_IP 4028 | jq
{
  "SESSION": [
    {
      "SessionID": "VI2LCs8i"
    }
  ],
  "STATUS": [
    {
      "Code": 319,
      "Description": "LUXminer 0.1.0-15436f7140",
      "Msg": "Session information",
      "STATUS": "S",
      "When": 1667917088
    }
  ],
  "id": 1
}

This command will never fails, and will return either a valid identifier or a blank string ("") in the SessionID field. This is useful as a soft check before issuing a logon and/or to show the existence of a running session to the user.

If using this command for checking purposes, you still need to correctly handle the result of the logon call, since someone could have created a new session between the checking time and the logon call.

⚠️

Since this command returns the active SessionID, you could use that to run your commands or even discard other people's sessions. This is called session stealing.

Don't do that. As with the kill command, if everyone just started misbehaving, no script will ever be able to properly work and integrate in a complex environment.

Getting Started Available Commands