search

koma75 / crowdutil

Atlassian Crowd utility cli tool
MIT License
1 stars 0 forks source link

readme

crowdutil

NO LONGER MAINTAINED

About

crowdutil is a set of utility command-line tool to help administer Atlassian Crowd users and groups.

日本語ドキュメントは こちら

Usage

Installation

npm install crowdutil

or directly from github

npm install https://github.com/koma75/crowdutil.git

Initial setup

You will need to create a settings file that hosts the directory options for crowd (with login information) to supply to the tool. The config file is a json file "crowdutil.json" and needs to be provided via command-line, $PWD/crowdutil.json or $HOME/.crowdutil/config.json.

CROWD setup

You will need to set up an application in CROWD for each directory you would like to manage through crowdutil.

See Atlassian Crowd Documentation (Adding an Application) for details.

  1. Login to your CROWD server using an administrator account
  2. Select the Application menu
  3. Add Application for each directory
    1. Details
      • Select Generic Application for Application Type
      • Type the name
      • set the password to use.
    2. Connection
      • URL should be the host name of one of your hosts you will use crowdutil on.
    3. Directories
      • Select one directory to associate to
    4. Authentication
      • leave blank
    5. Confirmation
      • confirm and add application
  4. Go to Search Applications and select the application you have made
  5. select the Remote Addresses Tab
  6. add all the remote addresses (IP or resolvable Hostname) that you plan to use crowdutil on.
  7. repeat steps 3-6 for all target directories.

Configuration file

Configuration file hosts the settings for the tool. You may specify the configuration file to read from the command line option --config (-c) or crowdutil will check $PWD/crowdutil.json, then $HOME/.crowdutil/config.json for possible configuration file to read from if not option is omitted.

the configuration file is a hash table in the following format:

Sample configuration file

{
  "directories": {
    "test": {
      "crowd": {
        "base": "http://localhost:8059/crowd/"
      },
      "application": {
        "name": "test application",
        "password": "pass123"
      }
    },
    "sample1": {
      "crowd": {
        "base": "http://localhost:8059/crowd/"
      },
      "application": {
        "name": "sample application 1",
        "password": "pass123"
      }
    }
  },
  "defaultDirectory": "test",
  "logConfig": {
    "appenders": [
      {
        "type": "file",
        "filename": "./crowdutil.log",
        "maxLogSize": "204800",
        "backups": 2,
        "category": "crowdutil"
      }
    ],
    "replaceConsole": false
  }
}

create-user

create a user in the specified directory.

crowdutil create-user -D directory -f firstname -l lastname -d dispname \
  -e user@example.com -u username -p password

search-user

search a user in the specified directory. wildcards ( * ) can be used for each field. all fields are searched with an AND operator.

crowdutil search-user -D directory -f firstname -l lastname \
  -e email -u username

update-user

update a user in the specified directory. Any non-specified value will be unchanged.

crowdutil update-user -D directory -f firstname -l lastname -d dispname \
  -e user@example.com -u username -a [true|false]

create-group

create a group in the specified directory

crowdutil create-group -D directory -n groupname -d "group description"

add-to-groups

add multiple users to a set of groups. All users specified will be added to all the groups specified.

crowdutil add-to-groups -D directory -g group1,group2,group3 \
  -u user1,user2,user3,user4

list-group

list the group membership of the specified user

crowdutil list-group -D directory -u uid

list-member

list the members of the specified group

crowdutil list-member -D directory -g group1

is-member

Check if specified users are members of the specified groups

crowdutil is-member -D directory -g group1,group2,group3 \
  -u user1,user2,user3,user4

rm-from-groups

remove multiple users from a set of groups. All users specified will be removed from all the groups specified.

crowdutil rm-from-groups -D directory -g group1,group2,group3 \
  -u user1,user2,user3,user4

empty-groups

empty out the specified groups so no users are direct members of the group. nested group members will not be removed

crowdutil empty-groups -D directory -g group1,group2,group3

batch-exec

Execute the specified batch file (a csv based batch file).

crowdutil batch-exec -D directory -b path/to/batchfile.csv

batchfile format

Basic format of the batch file is based on Jglr

The following cmmands can be used:

Any (optional) parameters should be left blank, but not skipped (except optional parameters at the very end). All excess parameters are ignored.

Invalid:

create-user,joed,john,doe,joed@example.com

Valid:

create-user,,joed,,john,doe,,joed@example.com
           ^     ^         ^
           these cannot be skipped.
update-user,,joed,true
                      ^ all trailing options can be omitted
empty-group,,groupname,foo,bar,baz,,,
           ^          ^ these are all ignored
           cannot be skipped

test-connect

test connection to selected directory.

crowdutil test-connect -D directory

create-config

Create a sample configuration file

crowdutil create-config -o sample.json

Known issues & Bugs

Development

basic structure

All library code is written with coffee script and reside in coffee_lib folder. Everything is compiled into lib/crowdutil folder.

The actual implementation of each commands are implemented in subcmd folder and configured via cmdlist.js. cmdlist.js hosts the command line option settings and entrypoints for each command. the subcommands are accessed via the command.js script.

compilation

  1. Initially, you will need to run "npm install" to install devDependencies.
    • Also install grunt-cli globally or set the path to the local install.
  2. Run "npm run build" to compile all coffee-script into the lib directory.
  3. While in development, you can run "npm run watch" to start the watch task, which will compile any changes.
    • You can also choose to run "npm run watch-test" which will only lint and compile the coffee-script files without minifying.
    • see the Gruntfile.coffee and package.json for all the possible tasks.

Pull-requests

Versioning

We will follow the semver2.0 versioning scheme.
With initial development phase starting at 0.1.0 and increasing minor/patch versions until we deploy the tool to production (and reach 1.0.0).

The interface relevant to versioning is whatever defined in this document's "Usage" section (includes all subcommands, their cli arguments, the format of the configuration file "crowdutil.json").

Change History

Date Version Changes
2016.01.25 1.0.2 Fix npm update issue for 1.0.0 and 1.0.1
Manually remove .git folder from install location to fix
2016.01.25 1.0.1 Fix file encoding for README.md
2016.01.22 1.0.0 Release as 1.0. Rename README.ja.md to README_ja.md for npmjs to properly show the english readme
2015.03.23 0.6.3 Fixed newline character for bin/crowdutil (from CRLF to LF)
2013.10.09 0.6.2 added --config option
default config path set to $HOME/.crowdutil/config.json
changed create-config to default to $HOME/.crowdutil/config.json
2014.08.22 0.6.1 added list-group command.
2014.08.22 0.6.0 added STDOUT messages separately from log message for use with other cli tools
fixed error handling for asynchronous functions.
added search-user command.
added list-member command.
added is-member command/batch-command.
2014.08.16 0.5.3 fixed issue with new line character
2014.07.25 0.5.2 fixed issue for batch exec not using proper directory
fixed parameter check bug
2014.04.22 0.5.0 added update-user command
changed the parameter ordering in the create-user batch file command to match the new update-user command.
2014.04.15 0.4.0 added batch-exec command
added create-config command
fixed a few README documentation errors
2014.04.02 0.3.2 fixed --help command
fixed vague command options ("-n, --name")
fixed debug logging of Objects
fixed command name of test-connection to test-connect, to fit inside the help
2014.04.02 0.3.0 logging feature implemented using log4js
added --verbose mode.
2014.03.28 0.2.1 documentation fix.
2014.03.28 0.2.0 parameter check implemented.
some command line options changed to optional
default directory option added
Fixed program execution path.
2014.03.24 0.1.0 First Release

License

The MIT License (MIT)

Copyright (c) 2014 Yasuhiro Okuno

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

documents

This readme file by Yasuhiro Okuno is licensed under CC-BY 3.0 international license.