Improve documentation

This commit is contained in:
Jan Dittberner 2016-09-24 21:59:01 +02:00
parent 20d5a86a71
commit 88d8a29a14
2 changed files with 367 additions and 54 deletions

View file

@ -6,6 +6,7 @@ This module defines `Celery`_ tasks to manage file system entities.
""" """
from __future__ import absolute_import, unicode_literals from __future__ import absolute_import, unicode_literals
from copy import deepcopy
import os import os
import subprocess import subprocess
from tempfile import mkstemp from tempfile import mkstemp
@ -68,15 +69,25 @@ def _build_mail_directory_name(username):
@shared_task @shared_task
def setup_file_sftp_userdir(username): def setup_file_sftp_userdir(username, *args, **kwargs):
""" """
This task creates the home directory for an SFTP user if it does not exist This task creates the home directory for an SFTP user if it does not exist
yet. yet.
:param str username: the username :param str username: the username
:raises Exception: if the SFTP directory of the user cannot be created :raises Exception: if the SFTP directory of the user cannot be created
:return: the created directory name :return: a dictionary with the key :py:const:`username` set to the
:rtype: str username value and a new key :py:const:`sftp_directory` set to the
path of the created SFTP directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.setup_file_sftp_userdir_chained`
at other positions in the task chain.
""" """
sftp_directory = _build_sftp_directory_name(username) sftp_directory = _build_sftp_directory_name(username)
@ -89,22 +100,54 @@ def setup_file_sftp_userdir(username):
sftp_directory], stderr=subprocess.STDOUT) sftp_directory], stderr=subprocess.STDOUT)
except subprocess.CalledProcessError as cpe: except subprocess.CalledProcessError as cpe:
log_and_raise( log_and_raise(
cpe, 'cold not create SFTP directory for user %s', username) cpe, 'could not create SFTP directory for user %s', username)
_LOGGER.info( _LOGGER.info(
'created sftp directory %s for user %s', sftp_directory, username) 'created sftp directory %s for user %s', sftp_directory, username)
return sftp_directory return {'username': username, 'sftp_directory': sftp_directory}
@shared_task @shared_task
def delete_file_sftp_userdir(username): def setup_file_sftp_userdir_chained(previous_result, *args, **kwargs):
"""
This task creates the home directory for an SFTP user if it does not exist
yet.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` key
:raises Exception: if the SFTP directory of the user cannot be created
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`sftp_directory` key set to the path of the created SFTP
directory
:rtype: dict
"""
username = previous_result['username']
retval = deepcopy(previous_result)
retval.update(setup_file_sftp_userdir(username))
return retval
@shared_task
def delete_file_sftp_userdir(username, *args, **kwargs):
""" """
This task recursively deletes the home directory of an SFTP user if it This task recursively deletes the home directory of an SFTP user if it
does not exist yet. exists.
:param str username: the username :param str username: the username
:raises Exception: if the SFTP directory of the user cannot be removed :raises Exception: if the SFTP directory of the user cannot be removed
:return: the removed directory name :return: a dictionary with the key :py:const:`username` set to the username
:rtype: str value and the new key :py:const:`sftp_directory` set to the path of the
deleted SFTP directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.delete_file_sftp_userdir_chained`
at other positions in the task chain.
""" """
sftp_directory = _build_sftp_directory_name(username) sftp_directory = _build_sftp_directory_name(username)
@ -117,11 +160,33 @@ def delete_file_sftp_userdir(username):
cpe, 'could not remove SFTP directory for user %s', username) cpe, 'could not remove SFTP directory for user %s', username)
_LOGGER.info( _LOGGER.info(
"deleted sftp directory %s of user %s", sftp_directory, username) "deleted sftp directory %s of user %s", sftp_directory, username)
return sftp_directory return {'username': username, 'sftp_directory': sftp_directory}
@shared_task @shared_task
def setup_file_mail_userdir(username): def delete_file_sftp_userdir_chained(previous_result, *args, **kwargs):
"""
This task recursively deletes the home directory of an SFTP user if it
exists.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` key
:raises Exception: if the SFTP directory of the user cannot be removed
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`sftp_directory` key set to the path of the removed SFTP
directory
:rtype: dict
"""
username = previous_result['username']
retval = deepcopy(previous_result)
retval.update(delete_file_sftp_userdir(username))
return retval
@shared_task
def setup_file_mail_userdir(username, *args, **kwargs):
""" """
This task creates the mail base directory for a user if it does not exist This task creates the mail base directory for a user if it does not exist
yet. yet.
@ -129,8 +194,18 @@ def setup_file_mail_userdir(username):
:param str username: the username :param str username: the username
:raises Exception: if the mail base directory for the user cannot be :raises Exception: if the mail base directory for the user cannot be
created created
:return: the created directory name :return: a dictionary with the key :py:const:`username` set to the
:rtype: str username value and a new key :py:const:`mail_directory` set to the path
of the created mail directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.setup_file_mail_userdir_chained`
at other positions in the task chain.
""" """
mail_directory = _build_mail_directory_name(username) mail_directory = _build_mail_directory_name(username)
@ -143,19 +218,52 @@ def setup_file_mail_userdir(username):
cpe, 'could not create mail base directory for user %s', username) cpe, 'could not create mail base directory for user %s', username)
_LOGGER.info( _LOGGER.info(
'created mail directory %s for user %s', mail_directory, username) 'created mail directory %s for user %s', mail_directory, username)
return mail_directory return {'username': username, 'mail_directory': mail_directory}
@shared_task @shared_task
def delete_file_mail_userdir(username): def setup_file_mail_userdir_chained(previous_result, *args, **kwargs):
"""
This task creates the mail base directory for a user if it does not exist
yet.
:param dict previous_result: a dictionary containing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` key
:raises Exception: if the mail base directory for the user cannot be
created
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`mail_directory` key set to the path of the created mail
directory
:rtype: dict
"""
username = previous_result['username']
retval = deepcopy(previous_result)
retval.update(setup_file_mail_userdir(username))
return retval
@shared_task
def delete_file_mail_userdir(username, *args, **kwargs):
""" """
This task recursively deletes the mail base directory for a user if it This task recursively deletes the mail base directory for a user if it
does not exist yet. does not exist yet.
:param str username: the username :param str username: the username
:raises Exception: if the mail base directory of the user cannot be removed :raises Exception: if the mail base directory of the user cannot be deleted
:return: the removed directory name :return: a dictionary with the key :py:const:`username` set to the
:rtype: str username value and a new key :py:const:`mail_directory` set to the path
of the deleted mail directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.delete_file_mail_userdir_chained`
at other positions in the task chain.
""" """
mail_directory = _build_mail_directory_name(username) mail_directory = _build_mail_directory_name(username)
@ -168,11 +276,32 @@ def delete_file_mail_userdir(username):
cpe, 'could not remove mail base directory of user %s', username) cpe, 'could not remove mail base directory of user %s', username)
_LOGGER.info( _LOGGER.info(
'deleted mail directory %s of user %s', mail_directory, username) 'deleted mail directory %s of user %s', mail_directory, username)
return mail_directory return {'username': username, 'mail_directory': mail_directory}
@shared_task
def delete_file_mail_userdir_chained(previous_result, *args, **kwargs):
"""
This task recursively deletes the mail base directory for a user if it
does not exist yet.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` key
:raises Exception: if the mail base directory of the user cannot be deleted
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`mail_directory` key set to the path of the deleted mail
directory
:rtype: str
"""
username = previous_result['username']
retval = deepcopy(previous_result)
retval.update(delete_file_mail_userdir(username))
return retval
@shared_task @shared_task
def create_file_mailbox(username, mailboxname): def create_file_mailbox(username, mailboxname, *args, **kwargs):
""" """
This task creates a new mailbox directory for the given user and mailbox This task creates a new mailbox directory for the given user and mailbox
name. name.
@ -180,8 +309,19 @@ def create_file_mailbox(username, mailboxname):
:param str username: the username :param str username: the username
:param str mailboxname: the mailbox name :param str mailboxname: the mailbox name
:raises Exception: if the mailbox directory cannot be created :raises Exception: if the mailbox directory cannot be created
:return: the created mailbox directory name :return: a dictionary with the keys :py:const:`username` and
:rtype: str :py:const:`mailboxname` set to the values of username and mailboxname
and a new key :py:const:`mailbox_directory` set to the path of the
created mailbox directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.create_file_mailbox_chained` at
other positions in the task chain.
""" """
mailbox_directory = os.path.join( mailbox_directory = os.path.join(
@ -197,19 +337,56 @@ def create_file_mailbox(username, mailboxname):
_LOGGER.info( _LOGGER.info(
'created mailbox directory %s for user %s', mailbox_directory, 'created mailbox directory %s for user %s', mailbox_directory,
username) username)
return mailbox_directory return {
'username': username, 'mailboxname': mailboxname,
'mailbox_directory': mailbox_directory
}
@shared_task @shared_task
def delete_file_mailbox(username, mailboxname): def create_file_mailbox_chained(previous_result, *args, **kwargs):
"""
This task creates a new mailbox directory for the given user and mailbox
name.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` and a :py:const:`mailboxname` key
:raises Exception: if the mailbox directory cannot be created
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`mailbox_directory` key set to the path of the created
mailbox directory
:rtype: dict
"""
username = previous_result['username']
mailboxname = previous_result['mailboxname']
retval = deepcopy(previous_result)
retval.update(create_file_mailbox(username, mailboxname))
return retval
@shared_task
def delete_file_mailbox(username, mailboxname, *args, **kwargs):
""" """
This task deletes the given mailbox of the given user. This task deletes the given mailbox of the given user.
:param str username: the username :param str username: the username
:param str mailboxname: the mailbox name :param str mailboxname: the mailbox name
:raises Exception: if the mailbox directory cannot be deleted :raises Exception: if the mailbox directory cannot be deleted
:return: the deleted mailbox directory name :return: a dictionary with the keys :py:const:`username` and
:rtype: str :py:const:`mailboxname` set to the values of username and mailboxname
and a new key :py:const:`mailbox_directory` set to the path of the
deleted mailbox directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use :py:func:`fileservertasks.tasks.delete_file_mailbox_chained` for
other positions in the task chain.
""" """
mailbox_directory = os.path.join( mailbox_directory = os.path.join(
@ -224,20 +401,56 @@ def delete_file_mailbox(username, mailboxname):
username) username)
_LOGGER.info( _LOGGER.info(
'deleted mailbox directory %s of user %s', mailbox_directory, username) 'deleted mailbox directory %s of user %s', mailbox_directory, username)
return mailbox_directory return {
'username': username, 'mailboxname': mailboxname,
'mailbox_directory': mailbox_directory
}
@shared_task
def delete_file_mailbox_chained(previous_result, *args, **kwargs):
"""
This task deletes the given mailbox of the given user.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` and a :py:const:`mailboxname` key
:raises Exception: if the mailbox directory cannot be deleted
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`mailbox_directory` key set to the path of the deleted
mailbox directory
:rtype: dict
"""
username = previous_result['username']
mailboxname = previous_result['mailboxname']
retval = deepcopy(previous_result)
retval.update(delete_file_mailbox(username, mailboxname))
return retval
@shared_task @shared_task
def create_file_website_hierarchy(username, sitename): def create_file_website_hierarchy(username, sitename, *args, **kwargs):
""" """
This task creates the directory hierarchy for a website. This task creates the directory hierarchy for a website.
:param str username: the username :param str username: the username
:param str sitename: name of the website :param str sitename: the sitename
:raises Exception: if the website directory hierarchy directory cannot be :raises Exception: if the website directory hierarchy directory cannot be
created created
:return: the directory name :return: a dictionary with the keys :py:const:`username` and
:rtype: str :py:const:`sitename` set to the values of username and sitename and a
new key :py:const:`website_directory` set to the path of the created
website directory
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use
:py:func:`fileservertasks.tasks.create_file_website_hierarchy_chained`
at other positions in the task chain
""" """
website_directory = os.path.join( website_directory = os.path.join(
@ -271,20 +484,55 @@ def create_file_website_hierarchy(username, sitename):
_LOGGER.info( _LOGGER.info(
'created website directory %s for user %s', website_directory, 'created website directory %s for user %s', website_directory,
username) username)
return website_directory return {
'username': username, 'sitename': sitename,
'website_directory': website_directory,
}
@shared_task @shared_task
def delete_file_website_hierarchy(username, sitename): def create_file_website_hierarchy_chained(previous_result, *args, **kwargs):
""" """
This task deletes the website hierarchy recursively. This task creates the directory hierarchy for a website.
:param str username: the user name :param dict previous_result: a dictionary describing the result of the
:param str sitename: name of the website previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` and a :py:const:`sitename` key
:raises Exception: if the website directory hierarchy directory cannot be :raises Exception: if the website directory hierarchy directory cannot be
deleted created
:return: the directory name :return: a copy of the :py:obj:`previous_result` dictionary with a new
:rtype: str :py:const:`website_directory` key set to the path of the created
website directory
:rtype: dict
"""
username = previous_result['username']
sitename = previous_result['sitename']
retval = deepcopy(previous_result)
retval.update(create_file_website_hierarchy(username, sitename))
return retval
@shared_task
def delete_file_website_hierarchy(username, sitename, *args, **kwargs):
"""
This task deletes a website hierarchy recursively.
:param str username: a username
:param str sitename: a site name
:return: a dictionary with the keys :py:const:`username` and
:py:const:`sitename` set to their original values and a new key
:py:const:`website_directory` set to the path of the deleted website
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use
:py:func:`fileservertasks.tasks.delete_file_website_hierarchy_chained`
at other positions in the task chain
""" """
website_directory = os.path.join( website_directory = os.path.join(
@ -300,20 +548,58 @@ def delete_file_website_hierarchy(username, sitename):
"website %s"), username, sitename) "website %s"), username, sitename)
_LOGGER.info( _LOGGER.info(
'deleted website directory %s of user %s', website_directory, username) 'deleted website directory %s of user %s', website_directory, username)
return website_directory return {
'username': username, 'sitename': sitename,
'website_directory': website_directory,
}
@shared_task @shared_task
def set_file_ssh_authorized_keys(username, ssh_keys): def delete_file_website_hierarchy_chained(previous_result, *args, **kwargs):
""" """
This task sets the authorized keys for ssh logins. This task deletes the website hierarchy recursively.
:param str username: the user name :param dict previous_result: a dictionary describing the result of the
:param list ssh_key: an ssh_key previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` and a :py:const:`sitename` key
:raises Exception: if the website directory hierarchy directory cannot be
deleted
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`website_directory` set to the path of the deleted website
directory
:rtype: dict
"""
username = previous_result['username']
sitename = previous_result['sitename']
retval = deepcopy(previous_result)
retval.update(delete_file_website_hierarchy(username, sitename))
return retval
@shared_task
def set_file_ssh_authorized_keys(username, ssh_keys, *args, **kwargs):
"""
This task set the authorized keys for ssh logins.
:param str username: a username
:param list ssh_keys: a list of ssh keys
:raises Exception: if the update of the creation or update of ssh :raises Exception: if the update of the creation or update of ssh
authorized_keys failed authorized_keys failed
:return: the name of the authorized_keys file :return: a dictionary with the keys :py:const:`username` and
:rtype: str :py:const:`ssh_keys` set to their original values and a new key
:py:const:`ssh_authorized_keys` set to the path of the SSH
authorized_keys file
:rtype: dict
.. note::
This variant can only be used at the beginning of a Celery task chain
or as a standalone task.
Use
:py:func:`fileservertasks.tasks.set_file_ssh_authorized_keys_chained`
at other positions in the task chain
""" """
ssh_authorized_keys_file = _build_authorized_keys_path(username) ssh_authorized_keys_file = _build_authorized_keys_path(username)
@ -354,4 +640,30 @@ def set_file_ssh_authorized_keys(username, ssh_keys):
log_and_raise( log_and_raise(
cpe, 'could not remove the authorized_keys file of user %s', cpe, 'could not remove the authorized_keys file of user %s',
username) username)
return ssh_authorized_keys_file return {
'username': username, 'ssh_keys': ssh_keys,
'ssh_authorized_keys': ssh_authorized_keys_file,
}
@shared_task
def set_file_ssh_authorized_keys_chained(previous_result, *args, **kwargs):
"""
This task sets the authorized keys for ssh logins.
:param dict previous_result: a dictionary describing the result of the
previous step in the Celery task chain. This dictionary must contain a
:py:const:`username` and a :py:const:`ssh_keys` key
:raises Exception: if the update of the creation or update of ssh
authorized_keys failed
:return: a copy of the :py:obj:`previous_result` dictionary with a new
:py:const:`ssh_authorized_keys` set to the path of the SSH
authorized_keys file
:rtype: dict
"""
username = previous_result['username']
ssh_keys = previous_result['ssh_keys']
retval = deepcopy(previous_result)
retval.update(set_file_ssh_authorized_keys(username, ssh_keys))
return retval

View file

@ -28,5 +28,6 @@ EOF
cat >/etc/salt/grains <<EOF cat >/etc/salt/grains <<EOF
roles: roles:
- fileserver - fileserver
- ldapclient
- gnuviechadmin.gvafile - gnuviechadmin.gvafile
EOF EOF