ClueNet:ClueAPI
From ClueWiki
Cluenet has included a selection of commands to be used with the remctl command. This allows you to make changes and obtain data that were not previously available to anyone that could not login to the administrative servers. Remctl allows anyone with sufficient access rights to run commands on a server that they do not have direct access to run commands on. This allows us to maintain a private and secure administrative server, and allow users to securely run commands the can only be run on the administrative server. There are 3 main categories of commands available; DNS, authorizedHostServices, and the IRC API commands.
Any command marked as "allowed by anyone" can be run by any person with valid Kerberos credentials, and those marked as "allowed by owners and authorized admins" require the user to have an authorizedAdmin attribute on that server's ldif.
Contents |
Client Setup
To run the commands on this page, you will need to be on a cluenet server with Kerberos set up, or have your personal computer configured to get a TGT from the KDC. You can set your computer up for this by following the Kerberos user tutorial. Then you will need to have the remctl-client package installed.
To install remctl on Debian/Ubuntu machines, run:
sudo apt-get install remctl-client
For Arch, use remctl from AUR.
Commands
Make sure you have used kinit to get a Kerberos ticket before using remctl.
Server management
dns refresh
Under the new DNS system, owners can change the DNS entries of their own servers using ldapmodify. The entry in the LDAP DB is not entered into the bind zone automatically though, so we have the following command. When run, this updates the zone files to include any changes in the DNS info stored on the LDAP server.
Usage:
remctl dns.api.cluenet.org dns refresh
Accessible to: everyone.
DNS slave configuration fetching
An official DNS slave server can use this command to fetch its configuration file.
remctl dns.api.cluenet.org dns getslaveconfig
keytab
In order for a server to allow users to login with a Kerberos ticket, the server has to have a valid Kerberos keytab. When run, this command will procure a keytab for the specified server.
Usage:
remctl hostadm.api.cluenet.org hostadm getkeytab server-principal > keytab-file
(example: host/arbelos.cluenet.org@CLUENET.ORG for a SSH keytab)
Accessible to: owner and authorized administrators of that server, as defined in the server's LDAP entry.
authorizedHostService management
Part of the new Cluenet authorization infrastructure allows admins to control access to individual aspects of their servers operations, such as limiting services controlled by pam, like ssh, sudo, su, email access, and several others. They can allow or deny individual users access to a service, instead of one single policy for all users.
Requirements: libpam-ldap_crispy (only available on Debian Lenny at the moment)
Usage:
To add access to a service for a specific user, the following is used.
remctl hostadm.api.cluenet.org hostadm addauthorizedhostservice username hostname service
And to remove a service for a user, use the following.
remctl hostadm.api.cluenet.org hostadm delauthorizedhostservice username hostname service
Accessible to: owner and authorized administrators of that server, as defined in the server's LDAP entry.
Notes:
- To allow everything, set service '*' (with quotes).
IRC Commands
DaVinci/ClueBot database
This set of commands allows you to access information collected by DaVinci from the IRC servers. This includes the nicknames, points, statistics on chatting, and others. There are also commands to allow authentication to the nickserv database, and allow admins to reset nickserv passwords.
Usage:
Dump header only:
remctl irc.api.cluenet.org irc cluebot dumpheader
This will dump the headers for the DaVinci database, this is just a list of the fields that is has information stored in.
Dump entries:
remctl irc.api.cluenet.org irc cluebot dump
This command will dump the entire database that DaVinci has.
remctl irc.api.cluenet.org irc cluebot dump nicks
Adding a comma-delimited list of nicks will return info on just those users.
Get points:
remctl irc.api.cluenet.org irc cluebot points
remctl irc.api.cluenet.org irc cluebot points nicks
These two commands are similar to the previous two, but they only return points.
Notes:
- nicks is a nickname or a comma-separated list of nicknames.
- Avoid doing full database dumps - rhombus' bandwidth is not infinite.
Checking NickServ password
Usage:
remctl irc.api.cluenet.org irc checknickservpass nickname password
User Management
SSH Blacklisting
Part of the new account creation process includes checking the requested ldap username against 2 blacklists. The first is a list of regular expressions that cover most derogatory, offensive, or abused usernames. The second checks against a list of usernames that are either used by the server to run services under, such as www-data or daemon, and local accounts that may be on the server. The first is simple vandal catching, the second negates any username collisions between LDAP and local accounts.
Usage:
remctl useradm.api.cluenet.org hostadm unameblacklistshow regex
This will output the regex list.
remctl useradm.api.cluenet.org hostadm unameblacklistshow plain
This is the list of specified usernames.
remctl useradm.api.cluenet.org hostadm unameblacklistshow # defaults to plain
Same thing as the last command.
remctl hostadm.api.cluenet.org hostadm unameblacklistadd <UsernameToBlacklist>
Any server owner/authorized administrator can use this command to add to the "plain" blacklist.
Username availability checking
The following command will check a username against the ldap database to see if it available.
remctl useradm.api.cluenet.org useradm checkunameavailability username
Changing nickname (clueIrcNick) in LDAP
This command allows you to reset your IRC nickname using the remctl API.
Usage:
remctl useradm.api.cluenet.org useradm changenick new-nick nickserv-password
Email Verification and Changing
Another section of user management is email verification and changing. The first command will provide you with the verification code needed to run the actual command to change your email address.
Usage:
remctl useradm.api.cluenet.org useradm sendemailverify <YourEmail>
This will send you your email verification code.
remctl useradm.api.cluenet.org useradm checkemailverification <Email> <VerificationCode>
This command is used to check the verification code for validity.
remctl useradm.api.cluenet.org useradm changeemail <NewEmailAddress> <VerificationCode>
This will check the verification code for validity, and allow you to change your email address.
User vouching
The new user account creation process will use a vouching system. The following commands are the basis for this system.
remctl useradm.api.cluenet.org useradm checkvouchcode nick code
This command will check a user's vouch code for validity.
remctl useradm.api.cluenet.org useradm initialvouch newusersnick
A current member with the LDAP attribute "authorizedService: initialVouch" can vouch for a new user in order for the account creation process to complete.
remctl useradm.api.cluenet.org useradm newacct username email nick emailverify ircpassword vouchcode
This command is used to create the user account. It verifies the vouchcode, nickserv password, and email verification code, and then creates an account in LDAP/Kerberos.
User account creation calls
The API is also what our account creation process is based off of. It uses a large set of commands for the creation of an account, and creation of responses. This section is detailed on ClueAPI Account System
