Merge pull request #199 from plasmabio/create-delete-multiple-users

Create and delete multiple student users

ansible/students-create.yml

@@ -0,0 +1,42 @@
+---
+
+- hosts: all
+  become: yes
+
+  vars:
+    default_user_group: plasma-users
+
+  tasks:
+    # Read a CSV file with users
+    - name: Read users from CSV file and return a list
+      read_csv:
+        path: "{{ studentdef }}"
+      register: users
+      delegate_to: localhost
+      become: no
+
+    - debug:
+        msg: "Read user {{ item.username }} with password {{ item.password }} in group {{ item.group }}"
+      loop: "{{ users.list }}"
+      delegate_to: localhost
+      become: no
+
+    - name: Add users
+      user:
+        name: "{{ item.username }}"
+        groups: "{{ item.group if item.group is defined else default_user_group }}"
+        password: "{{ item.password | password_hash('sha512') }}"
+        shell: /bin/bash
+        home: "{{ home_path if home_path is defined else '/home' }}/{{ item.username }}"
+      loop: "{{ users.list  }}"
+
+    - name: Set user quota
+      shell: |
+        setquota -u {{ item.username }} \
+        {{ item.quota.soft if item.quota.soft is defined else quota.soft }} \
+        {{ item.quota.hard if item.quota.hard is defined else quota.hard }} \
+        0 0 {{ quota_device_path }}
+      when: quota is defined or item.quota is defined
+      loop: "{{ users.list  }}"
+
+

ansible/students-remove.yml

@@ -0,0 +1,29 @@
+---
+
+- hosts: all
+  become: yes
+
+  vars:
+    default_user_group: plasma-users
+
+  tasks:
+    # Read a CSV file with users
+    - name: Read users from CSV file and return a list
+      read_csv:
+        path: "{{ studentdef }}"
+      register: users
+      delegate_to: localhost
+      become: no
+
+    - debug:
+        msg: "Read user {{ item.username }} in group {{ item.group }}"
+      loop: "{{ users.list }}"
+      delegate_to: localhost
+      become: no
+
+    - name: Remove users
+      user:
+        name: "{{ item.username }}"
+        state: absent
+        remove: yes
+      loop: "{{ users.list }}"

docs/configuration/batch-users.md

@@ -0,0 +1,67 @@
+(batch-users)=
+
+# Creating users in batches
+
+The {ref}`install-users` section details how to create the initial list of users.
+
+However in some cases it is useful to have a more automated way to create (and delete) users
+in batches. For example when preparing and cleaning up a group of students at the beginning and end of a semester.
+
+This section details how to create users defined in a CSV file using Ansible Playbooks.
+
+## Creating the CSV File
+
+Create the `student.csv` file which should contain the `username`, `password` and `group` columns.
+
+Here is an example of such file:
+
+```text
+username,password,group
+stu-megm1-01,bn3r7RjtOyg15X,megm1
+stu-megm1-02,2shgP3xK7aTuMN,megm1
+stu-megm1-03,Kh5jn4GuEIFIzY,megm1
+stu-megm1-04,g9gBHQjJ4VqQG1,megm1
+stu-megm1-05,73O88oFb6B1TB0,megm1
+stu-megm1-06,laZubrmgKBNg1x,megm1
+stu-megm1-07,gAONEMsgdz28si,megm1
+stu-megm1-08,tjlGadyELWj59M,megm1
+stu-megm1-09,soIb4txJDPjo1d,megm1
+stu-megm1-10,QjhalcW9Uq5wxo,megm1
+```
+
+````{warning}
+Since the fields in the CSV file are delimited by commas, passwords should not contain any `,` character.
+````
+
+## Running the playbooks
+
+To create the users, go to the `ansible/` folder and run the `student-create.yml` playbook with:
+
+```sh
+ansible-playbook student-create.yml -u ubuntu -e "studentdef=students.csv"
+```
+
+It is also possible to delete the users from the same CSV definition, using the `student-remove.yml` playbook:
+
+```sh
+ansible-playbook student-remove.yml -u ubuntu -e "studentdef=students.csv"
+```
+
+````{note}
+It is possible to pass additional parameters when creating users in batches.
+
+For example if you have a file defining disk quotas for a group of students:
+
+```yaml
+# default quotas for students
+quota:
+  soft: 200G
+  hard: 250G
+```
+
+You can run the playbook and reference that extra file:
+
+```bash
+ansible-playbook student-create.yml -u ubuntu -e "studentdef=students.csv" -e @students-config.yml
+```
+````

docs/configuration/index.md

@@ -5,6 +5,7 @@
 
 monitoring
 persistence
+batch-users
 resources
 cull
 namedservers

docs/install/users.md

@@ -231,3 +231,7 @@ foo       --     16K   5120M  10240M              4     0     0
 bar       --     16K  10240M  12288M              4     0     0
 #62583    --      4K      0K      0K              2     0     0
 ```
+
+### Creating user in batches
+
+The {ref}`batch-users` section details another way to create users in batches.