From 97fa971ad91d30bb0674d503dc92468c3d75eb0a Mon Sep 17 00:00:00 2001 From: René Genz Date: Dec 18 2017 13:08:56 +0000 Subject: Fix minor spelling mistakes --- diff --git a/design_pages/enhanced_nss_api.rst b/design_pages/enhanced_nss_api.rst index 347fc7c..0fc27d9 100644 --- a/design_pages/enhanced_nss_api.rst +++ b/design_pages/enhanced_nss_api.rst @@ -7,21 +7,21 @@ Related ticket(s): Problem statement ----------------- -The system-wide NSS API provided by glibc with calls like ``getpwnam`` etc +The system-wide NSS API provided by glibc with calls like ``getpwnam`` etc. might be a bottleneck for applications which are only interested in the data -provide by the SSSD backends. +provided by the SSSD backends. It would be possible to load SSSD's NSS plugin ``libnss_sss.so`` with ``dlopen`` and call the provided functions directly. But besides being a bit -cumbersome the API defined by NSS is limited and does not offer option to +cumbersome the API defined by NSS is limited and does not offer an option to control the behavior of the plugin. Hence a new API provider by SSSD to lookup -objects manages by SSSD would be beneficial. +objects managed by SSSD would be beneficial. Use cases --------- The first users of the new API would be the FreeIPA ``extdom`` and -``slapi-nis`` plugins. Both are use to make information about users and groups -from trusted domains available and hence are only interested results from SSSD. +``slapi-nis`` plugins. Both are used to make information about users and groups +from trusted domains available and hence are only interested in results from SSSD. Both plugins are run in threads of the 389ds directory server and to work efficiently the current mutex based locking of the connection of SSSD should be @@ -30,8 +30,8 @@ improved. Additionally ``slapi-nis`` caches results for performance reasons. Being a part of 389ds it will be notified if 389ds objects like e.g. id-overrides are modified and can drop the cached object. But since SSSD caches results as well -a new lookup of the modified object via slapi-nis might still return the old -result which will then stay in the cache of ``slapi-nis`` because no now +a new lookup of the modified object via ``slapi-nis`` might still return the old +result which will then stay in the cache of ``slapi-nis`` because no new modification is detected. As a result ``slapi-nis`` should be able to invalidate objects in the caches of SSSD to allow a refresh. The ``sss_cache`` is only of limited use here because it requires root privileges and currently @@ -39,13 +39,13 @@ invalidates the whole memory cache. Overview of the solution ------------------------ -The use cases that the new API should offer a timeout option so that an +Additional use cases should be supported by the new API. It should offer a timeout option so that an individual thread does not have to wait until the request is completely handled by SSSD but can abandon from the request and maybe check later if a result is available. -Additionally an option to invalidate the cached entires of an individual object -are needed. It would be possible to use a set of new calls for this but since +Additionally an option to invalidate the cached entries of an individual object +is needed. It would be possible to use a set of new calls for this but since most of the processing of such request and similar to the lookup requests it would be more straight forward to use a flag to indicate that the cached entry of the found object should be invalidated. @@ -66,8 +66,8 @@ Some of the flags might have influence on the client behavior. E.g. the flag to invalidate the cached entries of an object would tell the client to bypass the memory cache. This is needed because the memory cache will only contain the data of object which were directly requested. But the SSSD on-disk cache might -already contain data of objects which are lookup up indirectly, e.g. groups -during a initgroups request or users while looking up group members. So a +already contain data of objects which are looked up indirectly, e.g. groups +during an initgroups request or users while looking up group members. So a missing entry in the memory cache does not indicate that the entry is missing in the on-disk cache as well. Additionally memory cache and on-disk cache have different timeouts which would require the request to go directly to the SSSD @@ -215,7 +215,7 @@ The API of the new calls will be defined in ``sss_nss_idmap.h``:: * will contain the actual number of groups the * user belongs to. With a return value of 0 the * groups array was large enough to hold all group. - * With a return valu of ERANGE the array was not + * With a return value of ERANGE the array was not * large enough and ngroups will have the needed * size. * @param[in] flags flags to control the behavior and the results of @@ -364,7 +364,7 @@ As can be seen the existing calls from ``libsss_nss_idmap.so`` got a SSSD responder side ~~~~~~~~~~~~~~~~~~~ The SSSD NSS responder has to be prepared to accept the flags in the request. -Currently only a name or a ID are expected. To handle this new request types: +Currently only a name or an ID are expected. To handle this new request types: * SSS_NSS_GETPWNAM_EX * SSS_NSS_GETPWUID_EX @@ -372,18 +372,18 @@ Currently only a name or a ID are expected. To handle this new request types: * SSS_NSS_GETGRGID_EX * SSS_NSS_INITGR_EX -will be added. If the flags are not set will behave as the non-EX calls. +will be added. If the flags are not set, will behave as the non-EX calls. -If ``SSS_NSS_EX_FLAG_NO_CACHE`` is set ``cache_req_data_set_bypass_cache()`` +If ``SSS_NSS_EX_FLAG_NO_CACHE`` is set, ``cache_req_data_set_bypass_cache()`` will be called so that the cache-request framework will directly request new data from the backend. -If ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` is set +If ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` is set, ``cache_req_data_set_bypass_dp()`` (which will be implemented with this feature) will be called to only search the requested object in the cache. If it -was found the cached entry will be invalidate in both on-disk and memory cache. -If ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` was sent with SSS_NSS_INITGR_EX both -the groupmembership data and the plain user data will be invalidates. +was found, the cached entry will be invalidated in both on-disk and memory cache. +If ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` was sent with SSS_NSS_INITGR_EX, both +the groupmembership data and the plain user data will be invalidated. The flags ``SSS_NSS_EX_FLAG_NO_CACHE`` and ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` cannot be used at the same time. @@ -394,7 +394,7 @@ There are no configuration changes needed to use the new library calls. How To Test ----------- -To test the new calls should be used in C-programs. +To test the new calls they should be used in C-programs. How To Debug ------------ @@ -402,7 +402,7 @@ How To Debug the debug logs of the SSSD responder are available. If the ``SSS_NSS_EX_FLAG_NO_CACHE`` or ``SSS_NSS_EX_FLAG_INVALIDATE_CACHE`` are -used on the client side ``strace`` can be used to see is the client skips the +used on the client side, ``strace`` can be used to see whether the client skips the memory cache as expected. Authors diff --git a/developers/ipc.rst b/developers/ipc.rst index f2de45e..b5bd3b8 100644 --- a/developers/ipc.rst +++ b/developers/ipc.rst @@ -108,7 +108,7 @@ Describing the SBUS and public DBus interfaces Starting with upstream version 1.12, when the SSSD implemented its public DBus interface, the SSSD switched from hardcoding interface -names, methods etc in the source files directly to only describing the +names, methods etc. in the source files directly to only describing the interfaces in XML files using the `introspection format `__, which are then used to autogenerate message handlers, property getters