From ae9b4c274dc3061ee988fc2c463e552c9a41f02b Mon Sep 17 00:00:00 2001 From: Alexey Ovchinnikov Date: Mon, 28 Mar 2016 16:14:34 +0300 Subject: [PATCH] Shared File Systems service security guide fixes New concepts appearing in Mitaka are added. Also the guide is reworked to improve readability and make it easier to understand in general. Change-Id: I3d7bde2ccb3794e5025ec42695e9df2f5bb8dbbc --- security-guide/source/shared-file-systems.rst | 19 +- .../source/shared-file-systems/intro.rst | 162 +++++++++--------- .../network-and-security-models.rst | 162 ++++++++---------- .../source/shared-file-systems/policies.rst | 52 ++---- .../shared-file-systems/security-services.rst | 116 ++++++------- .../source/shared-file-systems/share-acl.rst | 55 +++--- .../shared-file-systems/share-type-acl.rst | 29 ++-- 7 files changed, 267 insertions(+), 328 deletions(-) diff --git a/security-guide/source/shared-file-systems.rst b/security-guide/source/shared-file-systems.rst index 4058b6b2..a3b1d22c 100644 --- a/security-guide/source/shared-file-systems.rst +++ b/security-guide/source/shared-file-systems.rst @@ -3,21 +3,20 @@ Shared File Systems =================== The Shared File Systems service (manila) provides a set of services for -management of shared file systems in a multi-tenant cloud environment, similar -to how OpenStack provides for block-based storage management through the -OpenStack Block Storage service project. With the Shared File Systems service, -you can create a remote file system, mount the file system on your instances, -and then read and write data from your instances to and from your file system. +management of shared file systems in a multi-tenant cloud environment. It is +done similar to how OpenStack provides block-based storage management through +the OpenStack Block Storage service project. With the Shared File Systems +service, you can create a shared file system and manage its properties such as +visibility, accessibility and usage quotas. -A large amount of existing software is designed around file-based storage. The -Shared File Systems service provides the management of file shares and works -with various storage providers that use following shared file system protocols: +The Shared File Systems service works with various storage providers that use +the following shared file system protocols: :term:`NFS `, :term:`CIFS `, :term:`GlusterFS`, and :term:`HDFS `. -The Shared File Systems serves the same purpose as the Amazon Elastic File -System (EFS) offering does. +The Shared File Systems service serves the same purpose as Amazon Elastic File +System (EFS). .. toctree:: :maxdepth: 2 diff --git a/security-guide/source/shared-file-systems/intro.rst b/security-guide/source/shared-file-systems/intro.rst index e24d6de5..33f369d1 100644 --- a/security-guide/source/shared-file-systems/intro.rst +++ b/security-guide/source/shared-file-systems/intro.rst @@ -3,37 +3,20 @@ Introduction ------------ The Shared File Systems service (manila) is intended to be ran on a single-node -or across multiple nodes. The Shared File Systems service consists of three +or across multiple nodes. The Shared File Systems service consists of four main services, which are similar to those of the Block Storage service: - ``manila-api`` - ``manila-scheduler`` - ``manila-share`` - -The Shared File Systems service uses a SQL-based central database that is -shared by all Shared File Systems services in the system. The amount and depth -of the data fits into a SQL database quite well. The Shared File Systems -service can use all SQL dialects supported by ORM SQLALchemy, but is tested -only with MySQL and PostgreSQL data bases. - -Using SQL, the Shared File Systems service is similar to other OpenStack -services and can be used with any OpenStack deployment. For more details on -the API, see the `OpenStack Shared File Systems API `_ description. For mode details of the CLI -using and configuring, see `Shared File Systems Administrator Guide -`_. - -Below is an explanation of the different components. - -.. image:: ../figures/manila-intro.png +- ``manila-data`` ``manila-api`` The service that provides a stable RESTful API. The service authenticates and routes requests throughout the Shared Filesystem service. There is python-manilaclient to interact with the API. For more details on the Shared File Systems API, see the `OpenStack - Shared File Systems API `_. + Shared File Systems API `_. ``manila-share`` Responsible for managing Shared File Service devices, specifically the back-end devices. @@ -41,11 +24,36 @@ Below is an explanation of the different components. Responsible for scheduling and routing requests to the appropriate ``manila-share`` service. It does that by picking one back-end while filtering all except one back-end. -python-manilaclient +``manila-data`` + This service is responsible for managing data operations which may take a + long time to complete and block other services if not handled separately. + +The Shared File Systems service uses an SQL-based central database that is +shared by all Shared File Systems services in the system. It can use any SQL +dialect supported by ORM SQLALchemy, but is tested only with MySQL and +PostgreSQL data bases. + +Using SQL, the Shared File Systems service is similar to other OpenStack +services and can be used with any OpenStack deployment. For more details on +the API, see the `OpenStack Shared File Systems API +`_ description. For more +details on the CLI usage and configuration, see `Shared File Systems Cloud +Administrative Guide +`_. + +On the image below you can see how different parts of the Shared File System +service interact with each other. + +.. image:: ../figures/manila-intro.png + +Besides already described services you can see two other entities on the +image: ``python-manilaclient`` and ``storage controller``. + +``python-manilaclient`` Command line interface to interact with the Shared File Systems service via ``manila-api`` and also a Python module to interact programmatically with the Shared File Systems service. -Storage controller +``Storage controller`` Typically a metal box with spinning disks, ethernet ports, and some kind of software that allows network clients to read and write files on the disks. There are also software-only storage controllers that run on @@ -56,72 +64,70 @@ Storage controller A share is a remote, mountable file system. You can mount a share to and access a share from several hosts by several users at a time. -The Shared File Systems service can work with different network types, which -can be flat, VLAN, VXLAN, or GRE, and supports segmented networking. There are +The Shared File Systems service can work with different network types: +flat, VLAN, VXLAN, or GRE, and supports segmented networking. There are also different :ref:`network plug-ins ` that provide a variety of integration approaches with the network services that are available with OpenStack. -There are a large number of share drivers created by different vendors. Each -share driver is a Python class that can be set for the back end and run in the -back end to manage the share operations, some of which are vendor-specific. -The back end is an instance of the manila-share service. For example, the -service can be configured to use NetApp Clustered Data ONTAP (cDOT), Huawei NAS -Driver, GlusterFS Native driver, and so on. +There are a large number of share drivers created by different vendors which +support different hardware storage solutions, for example, NetApp Clustered +Data ONTAP (cDOT) Driver, Huawei NAS Driver or GlusterFS Driver. Each share +driver is a Python class that can be set for a back end and run in the back +end to manage share operations, some of which can be vendor-specific. The back +end is an instance of the manila-share service. -The configuration information for clients for authentication and authorization +Clients' configuration data for authentication and authorization can be stored by :ref:`security services `. -This means that such protocols as LDAP and Kerberos, or with Microsoft Active -directory authentication service can be configured and used. +Such protocols as LDAP, Kerberos, or Microsoft Active Directory authentication +service can be configured and used. -Unless it is not modified in the ``policy.json``, either an administrator or -the tenant that owns a share always is able to manage the :ref:`access to the -shares ` by means of creating access rules with -authentication though IP address, user, group, or TLS certificates. The -authentication methods depend on which share driver and security service you -configure and use. +Unless it is not explicitly changed in the ``policy.json``, either an +administrator or the tenant that owns a share are able to manage +:ref:`access to the shares `. Access management is done by +creating access rules with authentication through IP address, user, group, or +TLS certificates. Available authentication methods depend on which share +driver and security service you configure and use. .. note:: - Different access features are supported by different share drivers with - taking into consideration the shared file system protocol. The supported - shared file system protocols are NFS, CIFS, GlusterFS, or HDFS. As the - example, the Generic (Block Storage as a back end) driver does not support - user and certificate authentication methods. It also does not support any - of the security services, such as LDAP, Kerberos, or Active Directory. For - details of supporting of features by different drivers, see `Manila share - features support mapping `_. + Different drivers support different access options depending on which + shared file system protocol is used. Supported shared file system protocols + are NFS, CIFS, GlusterFS, and HDFS. For example, the Generic (Block Storage + as a back end) driver does not support user and certificate authentication + methods. It also does not support any of the security services, such as + LDAP, Kerberos, or Active Directory. For details of features supported by + different drivers, see `Manila share features support mapping + `_. -As administrator, you can create the share types that enable the scheduler to -filter the back ends before you create a share. The share types have the extra -specifications you can set in the type for scheduler to filter and weigh back -ends so that an appropriate one is selected for the user that requests the -share creation. An administrator can add +As an administrator, you can create share types that enable the scheduler to +filter back ends before you create a share. Share types have extra +specifications that you can set for the scheduler to filter and weigh back +ends so that an appropriate one is selected for a user that requests +share creation. Shares and share types can be created as public or private. +This level of visibility defines whether other tenants are able to see these +objects and operate with them, or not. An administrator can add :ref:`access to the private share types ` for -definite users or tenants in the Identity service. Thus the users which you +specific users or tenants in the Identity service. Thus users which you have granted access can see available share types and create shares using them. -The shares and share types can be created as public or private. This level of -visibility defines whether other tenants are able to see these objects and -operate with them, or not. +Permissions for API calls for different users and their roles are determined +by :ref:`policies ` like in other OpenStack services. -The permissions of API calls for different users and their roles are determined -by :ref:`policies ` as well as other OpenStack services. - -The Identity service with different back ends, for example, LDAP, Active -Directory, can be used for the authentication in the Shared File Systems. See -details of the identity service security in :doc:`../identity` section. +The Identity service can be used for authentication in the Shared File +Systems service. See details of the Identity service security in +:doc:`../identity` section. General security information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Similar to other OpenStack projects, the Shared File Systems service is -registered with the Identity service, so you can find the API endpoints of the +registered with the Identity service, so you can find API endpoints of the share service v1 and v2 using **manila endpoints** command: .. code:: console + $ manila endpoints +-------------+-----------------------------------------+ | manila | Value | +-------------+-----------------------------------------+ @@ -146,12 +152,13 @@ By default, the Shared File Systems API service listens only on the port ``8786`` with ``tcp6`` type that supports both IPv4 and IPv6. .. note:: + The port ``8786`` is the default port for the Shared File Systems service. It may be changed to any other port, but this change should also be made - in the configuration file using option ``osapi_share_listen_port`` which + in the configuration file to option ``osapi_share_listen_port`` which defaults to ``8786``. -In ``/etc/manila/`` directory you can find the environment configuration files: +In the ``/etc/manila/`` directory you can find several configuration files: .. code:: console @@ -165,18 +172,15 @@ In ``/etc/manila/`` directory you can find the environment configuration files: share.filters It is recommended that you configure the Shared File Systems service to run -under a non-root service account, for example, ``manila`` and change file -permissions for only ``root`` to be able to modify the configuration files. The -Shared File Systems service expects that only the administrator can write to -the configuration files and the services can only read them through their group -membership in the ``manila`` group. Others must not be able to read these files -because the files contain admin passwords of different services. +under a non-root service account, and change file permissions so that only +the system administrator can modify them. The Shared File Systems service +expects that only administrators can write to configuration files and services +can only read them through their group membership in ``manila`` group. Others +must not be able to read these files because the files contain admin passwords +for different services. -Thus, for the configuration files it is recommended to set ownership to -``root/manila`` and access permissions to ``640`` allowing only root to write -to the configuration files, and other users in the ``manila`` group to read -them. For details, see :ref:`check_shared_fs_01` and :ref:`check_shared_fs_02` -in a checklist. +Apply checks :ref:`check_shared_fs_01` and :ref:`check_shared_fs_02` +from the checklist to verify that permissions are set properly. .. note:: @@ -187,5 +191,5 @@ in a checklist. .. tip:: - Manila configuration file ``manila.conf`` may be used from different places. - The path ``/etc/manila/manila.conf`` is one of expected paths by default. + The manila configuration file ``manila.conf`` may be placed anywhere. + The path ``/etc/manila/manila.conf`` is expected by default. diff --git a/security-guide/source/shared-file-systems/network-and-security-models.rst b/security-guide/source/shared-file-systems/network-and-security-models.rst index d74ea4ef..fabc3fdb 100644 --- a/security-guide/source/shared-file-systems/network-and-security-models.rst +++ b/security-guide/source/shared-file-systems/network-and-security-models.rst @@ -3,37 +3,37 @@ =========================== Network and security models =========================== -The share driver in the Shared File Systems service is a Python class that can -be set for the back end and run in it to manage the share operations, some of -which are vendor-specific. The back end is an instance of the manila-share -service. There are big number of the share drivers created by different vendors +A share driver in the Shared File Systems service is a Python class that can +be set for the back end and run in it to manage share operations, some of +which are vendor-specific. The back end is an instance of manila-share +service. There are a big number of share drivers created by different vendors in the Shared File Systems service. Each share driver supports one or more back -end modes: *share servers* and *no share servers*, but the administrator -chooses which mode is used by specifying it in the configuration file -``manila.conf``. +end modes: *share servers* and *no share servers*. An administrator +chooses which mode is used by specifying it in ``manila.conf`` configuration +file. An option ``driver_handles_share_servers`` is used for it. The *share servers* mode can be configured with flat network, or with segmented network. This depends on the network provider. -It is possible to have separate drivers for different modes on the same +It is possible to have separate drivers for different modes use the same hardware, if you want to have different configurations. Depending on which mode -is chosen, the administrator needs to provide additional details in the -configuration file as well. +is chosen, an administrator may need to provide more configuration details +through the configuration file. .. _share-servers-vs-no-share-servers: Share back ends modes --------------------- -Each share driver supports one or two of possible driver modes to configure the -back ends. Initially there are two driver modes for the back ends: +Each share driver supports at least one of the possible driver modes: * **share servers mode** * **no share servers mode** -The configuration option in the ``manila.conf`` file that set the share -servers mode or no share servers mode is the ``driver_handles_share_servers`` -option, that defines the driver mode for share storage life cycle management: +The configuration option in ``manila.conf`` that sets *share servers* mode or +*no share servers* mode is the ``driver_handles_share_servers`` +option. It indicates whether a driver handles share servers by itself +or it expects the Shared File Systems service to do it. .. list-table:: :header-rows: 1 @@ -54,24 +54,15 @@ option, that defines the driver mode for share storage life cycle management: storage with some net interface insteadof the presence of the share servers. -This is the share types which have the extra specifications that help scheduler -to filter back ends and choose the appropriate back end for the user that -requested to create a share. For details of managing the share types and -configuration the back ends, see `Share types -`_ -and `Multi-storage configuration -`_ -documentation. - No share servers mode In this mode, drivers have basically no network requirements whatsoever. - It's assumed that the actual storage controller(s) being managed by the + It's assumed that storage controller being managed by the driver has all of the network interfaces it's going to need. The Shared File Systems service will expect the driver to provision shares directly without creating any share server beforehand. This mode corresponds to - what some existing drivers are already doing, but it makes explicit the - choice for the administrator. In this mode, the share networks are not - needed at share creation time and must not be provided. + what some existing drivers are already doing, but it makes the + choice explicit for the administrator. In this mode, the share networks + are not needed at share creation time and must not be provided. .. note:: @@ -79,34 +70,34 @@ No share servers mode the network interfaces through which any shares are exported are already reachable by all tenants. -In the *no share servers* mode the share driver does not handle the storage -life cycle. The administrator is expected to handle the storage, network +In the *no share servers* mode a share driver does not handle storage +life cycle. An administrator is expected to handle the storage, network interfaces, and other host configurations. In this mode an administrator can -have the storage(s) as a host which exports the shares. The main characteristic +set storage as a host which exports shares. The main characteristic of this mode is that the storage is not handled by the Shared File Systems -service. The users in tenants share the common network(s), host, processor, and -network pipe. The users can hinder each other if there is no correct balancing -adjustment on the storage configured by admin or proxy before it. In the -public clouds it is possible that all the network pipe is used by one client, -so the administrator should handle this case not to happen. The balancing -adjustment can be configured by any means, not only OpenStack tools. +service. Users in a tenant share common network, host, processor, and +network pipe. They can hinder each other if there is no correct balancing +adjustment on the storage configured by admin or proxy before it. In +public clouds it is possible that all network capacity is used by one client, +so an administrator should care for this not to happen. Balancing +adjustment can be done by any means, not necessarily with OpenStack tools. Share servers mode - In this mode, the driver is able to create share servers and join them to - an existing network. When providing a new share server, the drivers expect + In this mode, a driver is able to create share servers and plug them to + existing networks. When providing a new share server, drivers expect an IP address and subnet from the Shared File Systems service. -Unlike the no share servers mode, in the *share servers* mode the users have -the share network and the share server that is created for each share network. +Unlike *no share servers* mode, in *share servers* mode users have +a share network and a share server that is created for each share network. Thus all users have separate CPU, amount of CPU time, network, capacity and throughput. -You also can configure the +You also can configure :ref:`security services ` in both *share servers* and *no share servers* back-end modes. But with *no share servers* back-end -mode, an administrator should set the desired authentication services manually -on the host. And in the *share servers* mode of the back end The Shared File -Systems service can be configured automatically with any of existing security +mode, an administrator should set desired authentication services manually +on the host. And in *share servers* mode the Shared File +Systems service can be configured automatically with any existing security services supported by the share driver. Flat vs segmented networking @@ -121,75 +112,68 @@ network: .. note:: - The Shared File Systems service is just keeping the information about the - networks in the database, and the real networks are available due to the + The Shared File Systems service is merely keeping the information about + networks in the database, and real networks are provided by the network provider. In OpenStack it can be Legacy networking (nova-network) - or Networking (neutron) services, but actually the Shared File Systems - service can work even out of OpenStack. That is due to the + or Networking (neutron) services, but the Shared File Systems + service can work even out of OpenStack. That is allowed by ``StandaloneNetworkPlugin`` that can be used with any network platform and does not require some specific network services in OpenStack like Networking or Legacy networking services. You can set the network parameters in its configuration file. -In the :ref:`share servers ` back-end mode -the share driver creates and manages the share server for each share network. -This mode can be divided on two variations: +In :ref:`share servers ` back-end mode +a share driver creates and manages a share server for each share network. +This mode can be divided in two variations: * Flat network in *share servers* back-end mode * Segmented network in *share servers* back-end mode -Initially, while creating the share network, you can set up either a network +Initially, when creating a share network, you can set up either a network and subnet of the OpenStack Networking (neutron) or a network of Legacy networking (nova-network) services. The third approach is to configure the -networking without Legacy networking and Networking services. The +networking without Legacy networking and Networking services. ``StandaloneNetworkPlugin`` can be used with any network platform. You can set -the network parameters in its configuration file. +network parameters in its configuration file. .. tip:: - All the share drivers that use the OpenStack Compute service do not use the - network plug-ins. In Liberty release it is Windows and Generic drivers, so - these share drives have other options and use different approach. + All share drivers that use the OpenStack Compute service do not use + network plug-ins. In Mitaka release it is Windows and Generic drivers. + These share drives have other options and use different approach. -After the share network is created, the Shared File Systems service retrieves -the network information determined by the network provider, for example, the -network type, the segmentation identifier if the network uses segmentation, the -IP block in Classless Inter-Domain Routing (CIDR) notation from which to -allocate the network. - -Below you can see the comparison of the flat network with segmented -network in *share servers* back-end mode. +After a share network is created, the Shared File Systems service retrieves +network information determined by a network provider: network type, +segmentation identifier if the network uses segmentation and +IP block in CIDR notation from which to allocate the network. **Flat network in share servers back-end mode** In this mode, some storage controllers can create share servers but due to -various limitations of the physical or logical network all of the share servers -have to be on a flat network. In this mode, the share driver needs something to -provision IP addresses for the share servers, but the IPs all come out of the +various limitations of physical or logical network all of share servers +have to be on a flat network. In this mode, a share driver needs something to +provision IP addresses for share servers, but IPs will all come out of the same subnet and that subnet itself is assumed to be reachable by all tenants. -In this mode, the :ref:`security service part ` of -the share networks is important because it allows tenants to specify security +The :ref:`security service part ` of +share networks ispecify security requirements such as AD or LDAP domains or a Kerberos realm. The Shared File -Systems service assumes that any hosts referred to in the security service are -reachable from the subnet where the share server is created, which limits the -situations where this mode makes sense. +Systems service assumes that any hosts referred to in security service are +reachable from a subnet where a share server is created, which limits the +number of cases where this mode could be used. **Segmented network in share servers back-end mode** -In this mode, the share driver is able to create share servers and join them to -an existing segmented network. The share drivers expect the Shared File systems -to provide for every new share server a subnet definition including a -segmentation type which is VLAN, VXLAN, or GRE, segmentation ID, and any other +In this mode, a share driver is able to create share servers and plug them to +an existing segmented network. Share drivers expect the Shared File Systems +service to provide a subnet definition for every new share server. This +definition should include segmentation type, segmentation ID, and any other info relevant to the segmentation type. -The security aspects of the configured networks depends on the configuration -itself and the network provider. - .. note:: - The share drivers may not support every type of segmentation, for details - see the specification for each driver. + Some share drivers may not support all types of segmentation, for details + see specification for the driver in use. .. _shared_fs_network_plugins: @@ -197,20 +181,18 @@ Network plug-ins ---------------- The Shared File Systems service architecture defines an abstraction layer for -network resource provisioning and allowing administrators to choose from a +network resource provisioning. It allows administrators to choose from different options for how network resources are assigned to their tenants’ -networked storage. There are a set of network plug-ins that provide a variety +networked storage. There are several network plug-ins that provide a variety of integration approaches with the network services that are available with OpenStack. -The network plug-ins allow to use any functions, configurations of the -OpenStack Networking and Legacy networking services, for example, you can use +Network plug-ins allow to use any functions, configurations of the +OpenStack Networking and Legacy networking services. One can use any network segmentation that the Networking service supports, you can use flat networks or VLAN-segmented networks of the Legacy networking -(nova-network) service, or you can use the plug-in for specifying networks +(nova-network) service, or you can use plug-ins for specifying networks independently from OpenStack networking services. For more information of how to use different network plug-ins, see `Shared File Systems service Network plug-ins `_. -The security in using different -network plug-ins depends on the specific network configuration. diff --git a/security-guide/source/shared-file-systems/policies.rst b/security-guide/source/shared-file-systems/policies.rst index 0d101461..e15e2f4f 100644 --- a/security-guide/source/shared-file-systems/policies.rst +++ b/security-guide/source/shared-file-systems/policies.rst @@ -9,14 +9,14 @@ the service's ``policy.json`` file. .. tip:: - The configuration file ``policy.json`` may be used from different places. - The path ``/etc/manila/policy.json`` is one of expected paths by default. + The configuration file ``policy.json`` may be placed anywhere. + The path ``/etc/manila/policy.json`` is expected by default. Whenever an API call to the Shared File Systems service is made, the policy engine uses the appropriate policy definitions to determine if the call can be accepted. -The policy rule determines under which circumstances the API call is permitted. +A policy rule determines under which circumstances the API call is permitted. The ``/etc/manila/policy.json`` file has rules where action is always permitted, when the rule is an empty string: ``""``; the rules based on the user role or rules; rules with boolean expressions. Below is a snippet of the @@ -29,53 +29,21 @@ OpenStack release to another it can be changed. "context_is_admin": "role:admin", "admin_or_owner": "is_admin:True or project_id:%(project_id)s", "default": "rule:admin_or_owner", - - "admin_api": "is_admin:True", - - "share:create": "", - "share:delete": "rule:default", - "share:get": "rule:default", - "share:get_all": "rule:default", - "share:list_by_share_server_id": "rule:admin_api", - "share:update": "rule:default", - "share:snapshot_update": "rule:default", - "share:create_snapshot": "rule:default", - "share:delete_snapshot": "rule:default", - "share:get_snapshot": "rule:default", - "share:get_all_snapshots": "rule:default", - "share:access_get": "rule:default", - "share:access_get_all": "rule:default", - "share:allow_access": "rule:default", - "share:deny_access": "rule:default", - "share:extend": "rule:default", - "share:shrink": "rule:default", - "share:get_share_metadata": "rule:default", - "share:delete_share_metadata": "rule:default", - "share:update_share_metadata": "rule:default", - "share:migrate": "rule:admin_api", - - "share_type:index": "rule:default", - "share_type:show": "rule:default", - "share_type:default": "rule:default", - - "share_instance:index": "rule:admin_api", - "share_instance:show": "rule:admin_api", - "share_extension:quotas:show": "", "share_extension:quotas:update": "rule:admin_api", "share_extension:quotas:delete": "rule:admin_api", "share_extension:quota_classes": "", - - ... } -Note that your users must be assigned to groups and roles that you refer to in -your policies. +Users must be assigned to groups and roles that you refer to in +your policies. This is done automatically by the service when user +management commands are used. .. note:: Any changes to ``/etc/manila/policy.json`` are effective immediately, which allows new policies to be implemented while the Shared File Systems - service is running. Modifying the policy can have unexpected side effects - and is not encouraged. For details, see `The policy.json file `_. + service is running. Manual modification of the policy can have unexpected + side effects and is not encouraged. For details, see + `The policy.json file `_. diff --git a/security-guide/source/shared-file-systems/security-services.rst b/security-guide/source/shared-file-systems/security-services.rst index 29ef69f6..49cc0a89 100644 --- a/security-guide/source/shared-file-systems/security-services.rst +++ b/security-guide/source/shared-file-systems/security-services.rst @@ -4,48 +4,46 @@ Security services ================= -For authentication and authorization of the clients, the Shared File Systems +For authentication and authorization of clients, the Shared File Systems Storage service can optionally be configured with different network authentication protocols. Supported authentication protocols are LDAP, -Kerberos, or Microsoft Active directory authentication service. +Kerberos, and Microsoft Active directory authentication service. Introduction to security services --------------------------------- -After creating the share and getting its export location users have no +After creating a share and getting its export location, users have no permissions to mount it and operate with files. The Shared File System service -allows to grant or deny access to the shares. +requires to explicitly grant access to the new share. -The configuration information for clients for authentication and authorization -(AuthN/AuthZ) can be stored by ``security services``. This means that such -protocols as LDAP and Kerberos, or with Microsoft Active directory -authentication service can be used by the Shared File Systems service if they -exist and are supported by the drivers and back ends. These authentication -services also can be configured without the Shared File Systems service. +The client configuration data for authentication and authorization +(AuthN/AuthZ) can be stored by ``security services``. LDAP, Kerberos, or +Microsoft Active directory can be used by the Shared File Systems service if +they are supported by used drivers and back ends. Authentication +services can also be configured without the Shared File Systems service. .. note:: - In some cases, it is required to add one of the security services. For - example, NetApp, EMC and Windows drivers require Active Directory for the - creation of shares with CIFS protocol. + In some cases, it is required to explicitly specify one of the security + services, for example, NetApp, EMC and Windows drivers require Active + Directory for the creation of shares with the CIFS protocol. Security services management ---------------------------- -A *security service* is the Shared File Systems service (manila) term that -means a set of options that defines a security domain for a particular shared -file system protocol, such as an Active Directory domain or a Kerberos domain. -The security service contains all of the information necessary for the Shared -File Systems to create a server that joins the given domain. +A *security service* is the Shared File Systems service (manila) entity that +abstracts a set of options that defines a security domain for a particular +shared file system protocol, such as an Active Directory domain or a Kerberos +domain. The security service contains all of the information necessary for +the Shared File Systems to create a server that joins a given domain. -Using the API users can create, update, view, delete a security service. -The security services are realized in the Shared File Systems API with such -key concepts: +Using the API, users can create, update, view and delete a security service. +Security Services are designed basing on the following assumptions: -* Tenants provide the details for the security service. +* Tenants provide details for the security service. * Administrators care about security services: they configure the server side of such security services. * Inside The Shared File Systems API, a ``security_service`` is associated with the ``share_networks``. -* The share drivers use the information in the security service to configure +* Share drivers use data in the security service to configure newly created share servers. While creating a security service, you can select one of these authentication @@ -72,35 +70,34 @@ services: - A directory service that Microsoft developed for Windows domain networks. Uses LDAP, Microsoft's version of Kerberos, and DNS. -The Shared File Systems allows you to configure a security service with these -options: +The Shared File Systems service allows you to configure a security service +with these options: * A DNS IP address that is used inside the tenant network. * An IP address or host name of a security service. * A domain of a security service. -* A user or group name that is used by the tenant. -* The password for the user, if you specify a user name. +* A user or group name that is used by a tenant. +* A password for a user, if you specify a user name. -An existing security service entity can be associated with the share network -entities that inform the Shared File Systems service about the security and +An existing security service entity can be associated with share network +entities that inform the Shared File Systems service about security and network configuration for a group of shares. You can also see the list of all security services for a specified share network and disassociate them from a share network. -For details of managing the security services via API, see the `Security -services API `_. You also can manage the security services via python-manilaclient, -see `Security services CLI managing `_. +For details of managing security services via API, see the `Security +services API `_. +You also can manage security services via python-manilaclient, +see `Security services CLI managing `_. -An administrator and the users as share owners can manage the -:ref:`access to the shares ` by means of creating access -rules with authentication though ip address, user or group, or TLS -certificates. The authentication methods depend on which share driver and +An administrator and users as share owners can manage the +:ref:`access to the shares ` by creating access +rules with authentication though an IP address, user, group, or TLS +certificates. Authentication methods depend on which share driver and security service you configure and use. -Thus as an administrator you can configure the backend to use the definite -authentication service via network and it will store the users. The +Thus, as an administrator, you can configure a back end to use specific +authentication service via network and it will store users. The authentication service can operate with clients without the Shared File System and the Identity service. @@ -108,37 +105,36 @@ and the Identity service. Different authentication services are supported by different share drivers. For details of supporting of features by different drivers, see - `Manila share features support mapping `_. - The support of definite authentication service by the driver also doesn't + `Manila share features support mapping `_. + Support for a specific authentication service by a driver does not mean that it can be configured with any shared file system protocol. Supported shared file systems protocols are NFS, CIFS, GlusterFS, and HDFS. - See the driver vendor's documentation for the specific driver and its - configuration for the security services. + See the driver vendor's documentation for infomation on a specific driver + and its configuration for security services. -Some drivers support the security services and other drivers do not support any -of the hereinabove security services. - -The Generic Driver with NFS or CIFS shared file system protocol supports only -authentication method through the IP address. +Some drivers support security services and other drivers do not support any +of the security services mentioned above. For example, Generic Driver with +the NFS or the CIFS shared file system protocol supports only authentication +method through the IP address. .. tip:: - * Those drivers that support CIFS shared file system protocol in most + * Those drivers that support the CIFS shared file system protocol in most cases can be configured to use Active Directory and manage access through - user authentication. - * Drivers that support GlusterFS protocol can be used with authentication - via TLS certificates. - * With drivers that support NFS protocol the authentication via IP address - is the only supported. + the user authentication. + * Drivers that support the GlusterFS protocol can be used with + authentication via TLS certificates. + * With drivers that support NFS protocol authentication via IP address + is the only supported option. * Since the HDFS shared file system protocol uses NFS access it also can be configured to authenticate via IP address. - The authentication via IP is the most weak. + Note, however, that authentication via IP is the least secure type of + authentication. The recommended configuration for the Shared File Systems service real usage -is to create a share with CIFS share protocol and add to it the Microsoft -Active Directory directory service. In this configuration you'll get the +is to create a share with the CIFS share protocol and add to it the Microsoft +Active Directory directory service. In this configuration you will get the centralized data base and the service that unites Kerberos and LDAP approaches. -This is a real use case that is convenient for the real production shared file +This is a real use case that is convenient for production shared file systems. diff --git a/security-guide/source/shared-file-systems/share-acl.rst b/security-guide/source/shared-file-systems/share-acl.rst index f37c4eb0..4f48dbc7 100644 --- a/security-guide/source/shared-file-systems/share-acl.rst +++ b/security-guide/source/shared-file-systems/share-acl.rst @@ -7,16 +7,16 @@ The Shared File Systems service allows to grant or deny access to different entities of the service for other clients. Having a share as remote mountable instance of a file system, you can manage -access to a specified share, and list the permissions for a specified share. +access to a specified share, and list permissions for a specified share. -The share can be *public* and *private*. This is a level of visibility for the +A share can be *public* or *private*. This is a level of visibility for the share that defines whether other tenants can or cannot see the share. By -default, the shares are created as private. While creating a share, use a key +default, all shares are created as private. While creating a share, use key :option:`--public` to make your share public for other tenants to see it in a list of shares and see its detailed information. According to a :ref:`policy.json ` file, an administrator -and the users as share owners can manage the access to the shares by means of +and the users as share owners can manage access to shares by means of creating access rules. Using :command:`manila access-allow`, :command:`manila access-deny` and :command:`manila access-list` commands, you can grant, deny and list access to a specified share correspondingly. @@ -25,19 +25,19 @@ you can grant, deny and list access to a specified share correspondingly. By default, when a share is created and has its export location, the Shared File Systems service expects that nobody can access the share by mounting - it. Pay attention that the share driver you use can change this + it. Please note that the share driver you use can change this configuration, or it can be directly changed on the share storage. To - ensure the access to the share, check the mounting config for the export + ensure access to the share, check the mounting config for the export protocol. -When the share is just created there are no created access rules and expected -permission to mount a share. This is obtained by the mounting config for the -certain export protocol. For example, for the NFS protocol there is -``exportfs`` command or ``/etc/exports`` file on the storage which controls -each remote share and the hosts that can access it. It is empty if nobody can -mount a share. For the remote CIFS server there is ``net conf list`` command -which shows the configuration. The parameter ``hosts deny`` should be set by -the share driver to ``0.0.0.0/0`` which means that that hosts are denied to +When a share is just created there are no default access rules associated with +it and permission to mount it. This could be seen in mounting config for +export protocol in use. For example, there is an NFS command ``exportfs`` or +``/etc/exports`` file on the storage which controls each remote share and +defines hosts that can access it. It is empty if nobody can mount a share. +For a remote CIFS server there is ``net conf list`` command +which shows the configuration. ``hosts deny`` parameter should be set by +the share driver to ``0.0.0.0/0`` which means that any host is denied to mount the share. Using the Shared File Systems service, you can grant or deny access to a share @@ -49,17 +49,17 @@ by specifying one of these supported share access levels: .. tip:: - The RO access level can be helpful in the public shares when the + The RO access level can be helpful in public shares when the administrator gives read and write (RW) access for some certain editors or contributors and gives read-only (RO) access for the rest of users (viewers). You must also specify one of these supported authentication methods: -* **ip**. Authenticates an instance through its IP address. A valid format is +* **ip**. Authenticates an instance by its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0. -* **cert**. Authenticates an instance through a TLS certificate. Specify the +* **cert**. Authenticates an instance by a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. @@ -69,7 +69,7 @@ You must also specify one of these supported authentication methods: .. note:: - The supported authentication methods depend on which share driver, security + Supported authentication methods depend on which share driver, security service and shared file system protocol you configure and use. Supported shared file system protocols are NFS, CIFS, GlusterFS, and HDFS. Supported security services are LDAP, Kerberos protocols, or Microsoft Active @@ -78,21 +78,21 @@ You must also specify one of these supported authentication methods: org/developer/manila/devref/share_back_ends_feature_support_ mapping.html>`_. -To verify that the access rules (ACL) were configured correctly for a share, -you can list permissions for a share. +To verify that access rules (ACL) were configured correctly for a share, +you can list its permissions. .. tip:: You also can choose and add the :ref:`security service ` that is supported by the share driver to create access rules with authentication methods for clients that are - appropriate for your share. The supported security services are LDAP, + appropriate for your share. Supported security services are LDAP, Kerberos and Microsoft Active Directory. -Below is an example of the NFS share with the Generic driver. After the share +Below is an example of an NFS share with the Generic driver. After the share was created it has export location ``10.254.0.3:/shares/share-b2874f8d-d428-4a5c-b056-e6af80a995de``. If you try -to mount it on the host with ``10.254.0.4`` IP address, you'll get the +to mount it on the host with ``10.254.0.4`` IP address, you'll get a *"Permission denied"* message. .. code:: console @@ -151,12 +151,3 @@ Now we can mount a share on the host with IP address ``10.254.0.4`` and have # ls -a /mnt . .. 1.txt lost+found # - -You also can list the access rules to each share and deny the access using the -Shared File Systems service CLI. - -.. tip:: - - To ensure that the granted or denied access with Shared File Systems - service CLI is correct, check the mount config file on the storage before - releasing a share to the production. diff --git a/security-guide/source/shared-file-systems/share-type-acl.rst b/security-guide/source/shared-file-systems/share-type-acl.rst index ce01d963..8971bd6e 100644 --- a/security-guide/source/shared-file-systems/share-type-acl.rst +++ b/security-guide/source/shared-file-systems/share-type-acl.rst @@ -8,7 +8,7 @@ tenant visible description, and a list of non-tenant-visible key-value pairs - extra specifications. The manila-scheduler uses extra specifications to make scheduling decisions, and drivers control the share creation. -The administrators can create and delete share types, and manage the extra +An administrator can create and delete share types, and also manage extra specifications that give them meaning inside the Shared File Systems service. Tenants can list the share types and can use them to create new shares. For details of managing the share types, see `Shared File Systems API @@ -17,26 +17,25 @@ details of managing the share types, see `Shared File Systems API `_ documentation. -The shares types can be created as *public* and *private*. This is the level of +Share types can be created as *public* and *private*. This is the level of visibility for the share type that defines whether other tenants can or cannot see it in a share types list and use it to create a new share. -By default, the share types are created as public. While creating a share type, +By default, share types are created as public. While creating a share type, use :option:`--is_public` parameter set to ``False`` to make your share type -private for other tenants not to see it in a list of share types and create -new share with it. +private which will prevent other tenants from seeing it in a list of share +types and creating new shares with it. On the other hand, *public* share +types are available to every tenant in a cloud. -The *public* share types are available to every tenant in a cloud. - -The Shared File Systems service allows the administrators to grant or deny -access to the *private* share types for some certain tenants. You also can get +The Shared File Systems service allows an administrator to grant or deny +access to the *private* share types for tenants. It is also possible to get information about access for a specified private share type. .. tip:: - Since the share types due to their extra specifications help to filter or + Since share types due to their extra specifications help to filter or choose back ends before users create a share, using access to the share - types you can limit clients that can choose definite back end. + types you can limit clients in choice of specific back ends. As an example, being an administrator user in admin tenant, you can create a private share type named ``my_type`` and see it in the list. In the console @@ -58,7 +57,7 @@ provided to show the current logged in user. | 5..| default| public | YES | driver_handles_share_servers:True | snapshot_support:True | +----+--------+-----------+-----------+-----------------------------------+-----------------------+ -The demo user in demo tenant can list the types and the private share type +``demo`` user in ``demo`` tenant can list the types and the private share type named ``my_type`` is not visible for him. .. code:: console @@ -75,7 +74,7 @@ named ``my_type`` is not visible for him. | 5..| default| public | YES | driver_handles_share_servers:True| snapshot_support:True| +----+--------+-----------+-----------+----------------------------------+----------------------+ -The administrator can grant the access to the private share type for the demo +The administrator can grant access to the private share type for the demo tenant with the tenant ID equal to df29a37db5ae48d19b349fe947fada46: .. code:: console @@ -94,7 +93,7 @@ tenant with the tenant ID equal to df29a37db5ae48d19b349fe947fada46: +----------------------------------+--------------------+ $ manila type-access-add my_type df29a37db5ae48d19b349fe947fada46 -Thus now the users in demo tenant can see the private share type and use it in +Thus now users in demo tenant can see the private share type and use it in the share creation: .. code:: console @@ -120,5 +119,5 @@ To deny access for a specified project, use A **real production use case** that shows the purpose of a share types and access to them is a situation when you have two back ends: cheap LVM as a public storage and expensive Ceph as a private storage. In this case you - can grant access to the certain tenants and make the access with + can grant access to certain tenants and make the access with ``user/group`` authentication method.