<commit_before>
# `krb5_principal(options, [goptions], callback)`

Create a new Kerberos principal with a password or an optional keytab.   

## Options

*   `kadmin_server`   
    Address of the kadmin server; optional, use "kadmin.local" if missing.   
*   `kadmin_principal`   
    KAdmin principal name unless `kadmin.local` is used.   
*   `kadmin_password`   
    Password associated to the KAdmin principal.   
*   `principal`   
    Principal to be created.   
*   `password`   
    Password associated to this principal; required if no randkey is
    provided.   
*   `randkey`   
    Generate a random key; required if no password is provided.   
*   `keytab`   
    Path to the file storing key entries.   
*   `log`   
    Function called with a log related messages.   
*   `ssh` (object|ssh2)   
    Run the action on a remote server using SSH, an ssh2 instance or an
    configuration object used to initialize the SSH connection.   
*   `stdout` (stream.Writable)   
    Writable EventEmitter in which the standard output of executed commands will
    be piped.   
*   `stderr` (stream.Writable)   
    Writable EventEmitter in which the standard error output of executed command
    will be piped.   

## Keytab example

```js
require('mecano').krb5_addprinc({
  principal: 'myservice/my.fqdn@MY.REALM',
  randkey: true,
  keytab: '/etc/security/keytabs/my.service.keytab',
  uid: 'myservice',
  gid: 'myservice',
  kadmin_principal: 'me/admin@MY_REALM',
  kadmin_password: '<PASSWORD>',
  kadmin_server: 'localhost'
}, function(err, modified){
  console.log(err ? err.message : 'Principal created or modified: ' + !!modified);
});
```

## Source Code

    module.exports = (options, callback) ->
      wrap @, arguments, (options, callback) ->
        return callback new Error 'Property principal is required' unless options.principal
        return callback new Error 'Password or randkey missing' if not options.password and not options.randkey
        modified = false
        do_kadmin = ->
          # options.realm ?= options.principal.split('@')[1] # Break cross-realm principals
          options.realm ?= options.kadmin_principal.split('@')[1] if /.*@.*/.test options.kadmin_principal
          # options.principal = options.principal.split('@')[0] if options.principal.indexOf(options.realm) isnt -1
          options.principal = "#{options.principal}@#{options.realm}" unless /^\S+@\S+$/.test options.principal
          cmd = misc.kadmin options, if options.password
          then "addprinc -pw #{options.password} #{options.principal}"
          else "addprinc -randkey #{options.principal}"
          # if options.password
          #   addprinc = misc.kadmin options, "addprinc -pw #{options.password} #{options.principal}"
          #   cmd = """
          #   ! echo #{options.kadmin_password} | kinit #{options.kadmin_principal} >/dev/null; && {
          #     #{addprinc}
          #   }
          #   """
          # else
          #   listprincs = misc.kadmin options, "listprincs"
          #   addprinc = misc.kadmin options, "addprinc -randkey #{options.principal}"
          #   cmd = """
          #   ! #{listprincs} | grep #{options.principal}; && {
          #     #{addprinc}
          #   }
          #   """
          execute
            cmd: cmd
            ssh: options.ssh
            log: options.log
            stdout: options.stdout<commit_msg>krb5_addprinc: remove old comments<commit_after>
# `krb5_principal(options, [goptions], callback)`

Create a new Kerberos principal with a password or an optional keytab.   

## Options

*   `kadmin_server`   
    Address of the kadmin server; optional, use "kadmin.local" if missing.   
*   `kadmin_principal`   
    KAdmin principal name unless `kadmin.local` is used.   
*   `kadmin_password`   
    Password associated to the KAdmin principal.   
*   `principal`   
    Principal to be created.   
*   `password`   
    Password associated to this principal; required if no randkey is
    provided.   
*   `randkey`   
    Generate a random key; required if no password is provided.   
*   `keytab`   
    Path to the file storing key entries.   
*   `log`   
    Function called with a log related messages.   
*   `ssh` (object|ssh2)   
    Run the action on a remote server using SSH, an ssh2 instance or an
    configuration object used to initialize the SSH connection.   
*   `stdout` (stream.Writable)   
    Writable EventEmitter in which the standard output of executed commands will
    be piped.   
*   `stderr` (stream.Writable)   
    Writable EventEmitter in which the standard error output of executed command
    will be piped.   

## Keytab example

```js
require('mecano').krb5_addprinc({
  principal: 'myservice/my.fqdn@MY.REALM',
  randkey: true,
  keytab: '/etc/security/keytabs/my.service.keytab',
  uid: 'myservice',
  gid: 'myservice',
  kadmin_principal: 'me/admin@MY_REALM',
  kadmin_password: '<PASSWORD>',
  kadmin_server: 'localhost'
}, function(err, modified){
  console.log(err ? err.message : 'Principal created or modified: ' + !!modified);
});
```

## Source Code

    module.exports = (options, callback) ->
      wrap @, arguments, (options, callback) ->
        return callback new Error 'Property principal is required' unless options.principal
        return callback new Error 'Password or randkey missing' if not options.password and not options.randkey
        modified = false
        do_kadmin = ->
          # options.realm ?= options.principal.split('@')[1] # Break cross-realm principals
          options.realm ?= options.kadmin_principal.split('@')[1] if /.*@.*/.test options.kadmin_principal
          # options.principal = options.principal.split('@')[0] if options.principal.indexOf(options.realm) isnt -1
          options.principal = "#{options.principal}@#{options.realm}" unless /^\S+@\S+$/.test options.principal
          cmd = misc.kadmin options, if options.password
          then "addprinc -pw #{options.password} #{options.principal}"
          else "addprinc -randkey #{options.principal}"
          execute
            cmd: cmd
            ssh: options.ssh
            log: options.log
            stdout: options.stdout
{'fraction_non_alphanumeric': 0.11077022444695624, 'fraction_numerical': 0.0027450347166155338, 'mean_word_length': 2.6869047619047617, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7432187', 'n_tokens_mistral': 1878, 'n_tokens_neox': 1841, 'n_words': 536}