Server side hook example - Alias lock/unlock

Introduction

• Provide the ability for IP owners/users to lock and unlock aliases via system hooks, thus removing the need for System Administrator involvement
• These hooks can be customized per customer for their particular needs.

Allowing non-admin users to lock/unlock an alias

By default, aliases cannot be locked or unlocked by non-admin users, however, an iplv-alias server side hook can be used to customize this behavior.

When an iplv-alias server side hook is defined, any user with RW permissions on the line can run the alias lock/unlock command, and it is up to the hook to accept or reject this action. This allows customers to customize the behavior - for example, allowing regular users to lock/unlock some aliases, but only allowing admins to lock/unlock important aliases.

Note:  In order to make changes on a line, RW access is required independent of the logic in the iplv-alias server side hook. ie; This hook follows the standard permissions model for hooks.

Server side hook implementation

Note that this hook would adhere to the standard permissions model hooks, ie: the user is required to have R/W access on the target IP Line.

This hook will pass a payload containing the relevant information to the alias action hook, and cancel the operation if the hook fails.

Some examples of server hook alias cases:

• check if the user performing an unlock is admin, else reject the unlock action
• check if a user is in a specific group, else reject the unlock action
• check if the alias being unlocked has a particular prefix (eg, "snap_", or "LOCK_"), then reject the unlock action 

Hook input payload format

See Server Side Hooks for more details on how to configure them.

{
  "operation": "string",     # lock/unlock
  "alias": {
    "id": "string",
    "name": "string"  }, 
  "ipv": {                    # lib.ip@version.line   
    "id": "string",   
    "fqn": {   
      "library": "string",
      "ip": "string",
      "version": integer,
      "line": "string"    }
  }, 
  "user": {                   # user who's performing the action 
    "id": "string", 
    "name": "string", 
    "is_admin": boolean
  },   
  "perms": {                 # permissions of the user on the line   
    "owner": boolean,   
    "read": boolean,   
    "write": boolean
  } 
} 

The exit code from the hook will be used to determine if the hook operation should continue or fail. If the exit value is not zero, the text written to stdout from the hook will be used as parameter to an error message.

Warning

Unlocking an alias is a potentially dangerous operation. For example if a particular alias was used during the tape out of a particular product, and this alias is unlocked and altered, there is no possibility to restore that tapeout anymore.

It is advised that unlock operations are done under controlled circumstances. There should be some record (preferably via a ticket tracking system) of:

• The requestor for the alias unlock
• The business justification for this action
• Approval from the IP owner(s) of the locked IPV alias.
• Approval from the IP owner(s) where this locked alias is used
  • Either the requestor or unlocker should run the pi ip usage --top command and check with each of those IP owners what the impact of the unlock action would be on those projects
• The unlocker who performed this action after approval (unlocking actions require admin privileges)

Validation of this unlock request is required with all impacted IP owners if this alias can be safely unlocked, to avoid breaking production designs. 

Example

Here is an example which allows any user to lock an alias, but only admin to unlock an alias:

#!/usr/bin/env python2.7

import json
import sys

def alias_lock(payload):
    operation = payload['operation']
    admin = payload['user']['is_admin']
    if operation == 'unlock':
        if not admin:
            print "Only admin users can unlock an alias"            sys.exit(1)


if __name__ == '__main__':
    payload = json.loads(sys.stdin.read())
    if sys.argv[1] == 'alias-lock':
        alias_lock(payload)