From 0ca6af4e13ad51659e6b14d0e27debda03c85ee0 Mon Sep 17 00:00:00 2001 From: tss24 <tss24@inf.ufpr.br> Date: Wed, 26 Feb 2025 22:40:47 -0300 Subject: [PATCH] Add README.md prototype --- README.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6e26693 --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ +# Useradm + +This command is a CLI for managing users and groups in a LDAP/KRB environment. + +## Installation + +To install, just clone the repo: + + git clone https://gitlab.c3sl.ufpr.br/tss24/useradm.git + +and build the binary: + + cd useradm + go build -o useradm + +if you want add it the go path use: + + go install + + +## Usage + +For each command given we want to know what we will interact with (user/group), +as well as the action (create/remove/etc). The command will be asking for +confirmation in commands where some change is made so you can preview and deny +if something is not as you wanted. + +Note 1: order of flags does not matter + +Note 2: most commands have the -y flag to skip the confirmation if you want + +### Show + +To show a user's info we can use: + + useradm user show [options] + +in flags the command needs identifiers to make the search, such as: + + useradm user show -n pedro -r 2024 -g bcc -i + +here we are searching for a user with name with pedro, grr with 2024, is part +of the group 'bcc' and -i is to make the search case insensitive. + + +### Create + +To create a user we can use: + + useradm user create [options] + +the command needs some basic info to create a user. The baseline is this: + + useradm user create -n "<User Full Name>" -g <User group> -c <User course> + +but if we run something like + + useradm user create -n "Joao da Silva" -g bcc -c bcc + +we will get an error. That is because the login generation needs the user GRR +for the default 'ini' login type. So this is now correct: + + useradm user create -n "Joao da Silva" -g bcc -c bcc -t last + +the auto generation will be explained in the section "Implementation" + +### Remove + +To remove a user, since the login name is guaranteed to be unique, we do: + + useradm user remove [username] + +then the users info will be displayed for confirmation and their account will +be removed from LDAP and Kerberos, their directories will end up at: + + home: /home/contas_removidas/<Year of removal>/ + webdir: /home/contas_removidas/html/<Year of removal>/ + webdir: /nobackup/contas_removidas/<Year of removal>/ + + +### Modify + +To modify a user we can do: + + useradm user mod [username] + +after pressing return a temp file with the user config will be opened in an +editor (based on your terminal varible $EDITOR). + +After editing you can save and exit the file and the modifications will be read, +shown for confirmation and applied. + +### Reset + +The most often used modification gets it's own command. + +To reset a user's password you can do: + + useradm user reset [flag] + +with no flag a password will be auto-generated. Passing the flag -p you can +specify the new password. Passwords need to be good lol. + +Note: Check "Implementation" to learn about kadmin.local command + +### Bulk + +TODO :)))))) + +### Migrate + +TODO :<<<<< + +### Evolve(?) + +TODO :&&&&&&& + + +## Implementation + +To make this binary I used Go's cobra CLI module since it is common and I wanted +to learn Go lol. It makes it easy to show help and parsing args/flags :D + +This command is the evolution of useradm.py and was heavily based on it. It had +no documentation besides the actual code with no comments. So for anyone that is +going to change this in the future I will now explain how things work. I will +now explain some not so obvious parts. + +### LDAP + +Since we use LDAP to store data about users I used the LDAP module to make and +send requests. A good example is `user show` to use that command we first get +all users and store them in a array of User models (structs). Then we filter +based on the user input. + +To connect to LDAP we need to connect to the socket, and bind it using some +credentials. From the time of writting this (26/02/2025) there is a password +file that is used for that in urquell lol. + +Then we generate the request that will give us all the users, get the response, +and store the result in structs. + +Many other requests are made in the code and you can learn the syntax by reading +it or via the docs of the module. + +### Kerberos + +You may have realized that we do not store user passords in LDAP. We store them +in Kerberos. After you created the LDAP entry you can create a KerberosPrincipal +for the user that will take care of authentication and tokens. When you create +a principal you need to set a password via the `kadmin.local` command, which is +cursed :p the command even returns 0 (success) even when the password change was +not accepted so the function for it is a little different (PS: don't judge me) + +### Validation + +The old command `useradm.py` didn't really validate the entries given and had no +confirmation. Because of that and some intelligence misfortunes there were/are +some users with messed up names, gecos, etc. So I made an effort on making a CLI +that minimizes those misfortunes. + +### Login generation + +`useradm.py` had 3 function to generate names that used a very wierd algorithm. +At first I just copied them, then I thought it was too long and repetitive so +I merged them into one (See commit e303dcc1). It was VERY ugly, so Fernando K. +helped and rewrote/improved the algorithm toa more mantainable state, thanks :) +(See commit e9762f8b) + +TODO: explain it + +TODO: finish... -- GitLab