The alternatives.json file

The alternatives.json file is a secondary, optional, part of the parcel metadata. It contains definitions for entries that should be registered with the system's alternatives system. Typically, these alternatives entries will be used to provide convenient access to programs inside the parcel (eg: Creating a /usr/bin/hdfs that points into the CDH parcel).

Alternatives Lifecycle

If alternatives are provided by a parcel, and if CM is configured to create them, then they will be created at the time the parcel is activated, and deleted when the parcel is deactivated. Implicitly this means that if you switch from one version of a parcel to another, the alternatives will be replaced by new ones pointing into the newly activated version.

Interaction with pre-existing alternatives entries

If the alternative being added is already a registered alternative (obviously with a different target) on the system, then the registration will happen, but the active target will only switch if the alternative is currently in auto mode and the new target priority is higher than the current one. Cloudera provided parcels deliberately have a low priority, on the basis that if there is an alternatives overlap, the other entry is probably the one the user wants. You can choose whatever priority level you want for your alternatives, but think about the implications of an overlap for your product.

Behaviour when alternatives entry collides with existing files/directories

If an alternatives entry has a destination that is currently occupied by another file or directory, then that file/directory will not be replaced by the alternative - this is a characteristic of how the alternatives system works and not parcel specific. It also happens to be the right thing to do - as we wouldn't want to overwrite a package-managed or user provided file.

If the non-alternative file is subsequently removed, something still has to poke alternatives to get the symlinks created. A simple way to do this is to restart the CM Agent, and this is something that's covered in the CM documentation.

An alternatives.json example

{
    "avro-tools": {
      "destination": "/usr/bin/avro-tools",
      "source": "bin/avro-tools",
      "priority": 10,
      "isDirectory": false
    },
    "beeline": {
      "destination": "/usr/bin/beeline",
      "source": "bin/beeline",
      "priority": 10,
      "isDirectory": false
    },
    "hadoop": {
      "destination": "/usr/bin/hadoop",
      "source": "bin/hadoop",
      "priority": 10,
      "isDirectory": false
    },
    "hbase-conf": {
      "destination": "/etc/hbase/conf",
      "source": "etc/hbase/conf.dist",
      "priority": 10,
      "isDirectory": true
    },
    "hbase-solr-conf": {
      "destination": "/etc/hbase-solr/conf",
      "source": "etc/hbase-solr/conf.dist",
      "priority": 10,
      "isDirectory": true
    },
    "hive-conf": {
      "destination": "/etc/hive/conf",
      "source": "etc/hive/conf.dist",
      "priority": 10,
      "isDirectory": true
    }
}

Fields

• Map Key: The alternative name.
• destination: The absolute path where the alternatives system will create the symlink
• source: The relative path within the parcel that the alternative should point to
• priority: The priority of the alternative. If multiple alternatives are registered for the same name, then the one with the highest priority wins, and if multiple entries exist at the same priority, then the first one to get registered wins.
• isDirectory: Is the alternative entry for a directory? CM has to handle files and directories slightly differently, so it's important to identify them correctly