An App that is used as a server in at least one client-server IPC split. More...
#include <app.hpp>
Public Types | |
| using | Master_set = boost::unordered_map< std::string, Server_app > |
Suggested type for storing master repository or all Server_appss. See App doc header for discussion. More... | |
| using | Client_app_set = boost::unordered_set< std::string > |
Short-hand for existence-checkable set of Client_apps via App::m_name. More... | |
 Public Types inherited from ipc::session::App | |
| using | Master_set = boost::unordered_map< std::string, App > |
Suggested type for storing master repository or all Appss. See App doc header for discussion. More... | |
Public Attributes | |
| Client_app_set | m_allowed_client_apps |
A given Client_app (as identified by its distinct App::m_name) may request to establish an IPC session with an instance of *this Server_app as the conversation partner process if and only if it is in this set. More... | |
| fs::path | m_kernel_persistent_run_dir_override |
| Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed for this particular application; leave empty to use the default system path instead. More... | |
| util::Permissions_level | m_permissions_level_for_client_apps |
Specifies level of access for Client_apps (which must, also, be in m_allowed_client_apps at any rate) as enforced by file system permissions. More... | |
| Public Attributes inherited from ipc::session::App | |
| std::string | m_name |
| Brief application name, readable to humans and unique across all other applications' names; used both as a short programmatic key in shared resource naming (including as a folder in Shared_name for kernel-persistent resources and addresses; and in path names – such as PID file name – in the file system). More... | |
| fs::path | m_exec_path |
Absolute, lexically normalized canonical path to the executable entity (which is not a directory), as it would appear in a command line or exec()-like invocation when actually invoking the application. More... | |
| util::user_id_t | m_user_id |
| The application must run as this user ID (UID). Files and other shared resources shall have this owner. More... | |
| util::group_id_t | m_group_id |
| The application must run as this group ID (GID). Files and other shared resources shall have this owner. More... | |
Related Functions | |
(Note that these are not member functions.) | |
| std::ostream & | operator<< (std::ostream &os, const Server_app &val) |
Prints string representation of the given Server_app to the given ostream. More... | |
| Related Functions inherited from ipc::session::App | |
| std::ostream & | operator<< (std::ostream &os, const App &val) |
Prints string representation of the given App to the given ostream. More... | |
Detailed Description
An App that is used as a server in at least one client-server IPC split.
This is explained in the "App, Client_app, Server_app registry conventions" section of the struct App doc header.
- See also
structApp doc header.
As explained there, each Server_app – in addition to the source App fields copied from an App in the master App repository – ultimately stores references (by App::m_name) to the Client_apps describing client apps that may initiate sessions with that Server_app.
Member Typedef Documentation
◆ Client_app_set
| using ipc::session::Server_app::Client_app_set = boost::unordered_set<std::string> |
Short-hand for existence-checkable set of Client_apps via App::m_name.
◆ Master_set
| using ipc::session::Server_app::Master_set = boost::unordered_map<std::string, Server_app> |
Friends And Related Function Documentation
◆ operator<<()
|
related |
Prints string representation of the given Server_app to the given ostream.
- Parameters
-
os Stream to which to write. val Object to serialize.
- Returns
os.
Definition at line 134 of file app.cpp.
References m_allowed_client_apps.
Member Data Documentation
◆ m_allowed_client_apps
| Client_app_set ipc::session::Server_app::m_allowed_client_apps |
A given Client_app (as identified by its distinct App::m_name) may request to establish an IPC session with an instance of *this Server_app as the conversation partner process if and only if it is in this set.
Definition at line 222 of file app.hpp.
Referenced by operator<<().
◆ m_kernel_persistent_run_dir_override
| fs::path ipc::session::Server_app::m_kernel_persistent_run_dir_override |
Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed for this particular application; leave empty to use the default system path instead.
Informally: In production it is recommended to leave this empty, as the default system path is a well known location (namely /var/run) where one would expect to find such files.
Kernel-persistent means that it'll disappear at reboot; runtime, but not temporary, means it's... not a thing that might be wiped spuriously anytime (informally: not /tmp). Informally: just know that it is normally /var/run, and that it stores things such as process-ID (PID) files.
It shall be a Unix path and absolute (starts with forward-slash) (and lacks a root-name). Informally it is probably best for it to be lexically normal as well.
Rationale
Why allow this override, if the default is sensible? Answer: The default usually requires admin privileges for writing. For test/debug purposes a location like /tmp or /tmp/var/run can be convenient.
◆ m_permissions_level_for_client_apps
| util::Permissions_level ipc::session::Server_app::m_permissions_level_for_client_apps |
Specifies level of access for Client_apps (which must, also, be in m_allowed_client_apps at any rate) as enforced by file system permissions.
Specifically, as of this writing, it determines at least the following items. Note that ownership is identified by the UID/GID settings (matching *this App::m_user_id and App::m_group_id) of various files and other shared resources created by the server* application in the ipc::session framework. (* - Actually, at times, resources are created by the client application too. See below.)
- File permissions set on the CNS (PID) file established by Session_server. A given Client_session (etc.) must read this file in order to know to which Session_server to issue a session-open request (establish a Session); if it cannot access that file, it cannot open a session against this Server_app.
- If this check fails, and everything is functioning as generally intended internally, then the below items are moot (as opening a session is a prerequisite for anything else).
- Permissions set on any SHM pool created for a given
"shm::*::Server_session". and"shm::*::Session_server". A Client_app may not be able to complete its session-open attempt (shm::classic::Client_session::sync_connect(), etc.) if its user lacks the permissions to open the underlying SHM-pool(s) resource in the file system.(It also conceivably may be able to complete the session-open but fail if opening a pool on-demand later; the session will then likely end prematurely. This depends on the inner workings of the particular SHM system chosen; shm::classic::Client_session opens pools during session-open procedure exclusively, but other systems may behave differently.)- Arena-lending SHM providers – as of this writing namely ipc::shm::arena_lend::jemalloc – involve both sides (session-server and session-client) each creating SHM pool(s) for allocations from within their respective processes. m_permissions_level_for_client_apps applies to the server-created pools, yes; but also client-created pools. At the moment it seems to me (ygoldfel) that nevertheless a common setting in Server_app still makes sense. In practice, it means this: If this is set to util::Permissions_level::S_USER_ACCESS, then the Client_app and Server_app UID/GID shall need to be equal; if util::Permissions_level::S_GROUP_ACCESS then just the GID (while UIDs ideally would be different).(Obviously if
S_UNRESTRICTEDthen does not matter.) Don't see the sense in making this a separate knob in Client_app. Maybe though? Not a formal to-do for now.
- Arena-lending SHM providers – as of this writing namely ipc::shm::arena_lend::jemalloc – involve both sides (session-server and session-client) each creating SHM pool(s) for allocations from within their respective processes. m_permissions_level_for_client_apps applies to the server-created pools, yes; but also client-created pools. At the moment it seems to me (ygoldfel) that nevertheless a common setting in Server_app still makes sense. In practice, it means this: If this is set to util::Permissions_level::S_USER_ACCESS, then the Client_app and Server_app UID/GID shall need to be equal; if util::Permissions_level::S_GROUP_ACCESS then just the GID (while UIDs ideally would be different).(Obviously if
- Similarly (to preceding bullet point, minus the
arena_lendcaveat) for bipc MQs. ipc::session opens such MQs (if so configured at compile-time) during session-open; hence on permissions failure the session-open will itself fail. - Similarly (to preceding bullet point) for POSIX MQs.
As of this writing the list is complete; however it is conceivable it may be analogously extended to more resources.
That list is actually not quite complete even as of this writing. The CNS (PID) file's shared-mutex is also subject to this, as are other similar shared-mutexes (in Linux, semaphores). However that's very Inside Baseball to mention in public docs.
Definition at line 288 of file app.hpp.
Referenced by ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().
The documentation for this struct was generated from the following files:
- session/app.hpp
- session/session_fwd.hpp
