osaf/services/saf/logsv/README_LONGDN | 138 ++++++++++++++++++++++++++++++++++ 1 files changed, 138 insertions(+), 0 deletions(-)
Show changes for long DN, including: 1) saflogger tool 2) log agent 3) log services 4) test suite diff --git a/osaf/services/saf/logsv/README_LONGDN b/osaf/services/saf/logsv/README_LONGDN new file mode 100644 --- /dev/null +++ b/osaf/services/saf/logsv/README_LONGDN @@ -0,0 +1,138 @@ +# +# -*- OpenSAF -*- +# +# (C) Copyright 2016 The OpenSAF Foundation +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. This file and program are licensed +# under the GNU Lesser General Public License Version 2.1, February 1999. +# The complete license can be accessed from the following location: +# http://opensource.org/licenses/lgpl-license.php +# See the Copying file included with the OpenSAF distribution for full +# licensing terms. +# +# Author(s): Ericsson AB +# + +I. GENERAL INFORMATION (#1315) +============================== + +The SaNameT type, which is used to pass distinguished stream DNs name in saLogStreamOpen_2() API, +or in `logSvcUsrName`, `notificationObject` or `notifyingObject` which belong to `SaLogRecordT` +data structure passed to `saLogWriteLogAsync()` API, contains a fixed-size buffer that limits +the string length to a maximum of 255 bytes. + +#1315 ticket was raised for LOG to support long DN. The use cases could be: +UC1) Write log records using the long DN in @Sl, @No, @Ng tokens using Log API. +UC2) Create any long DN name stream using Log API. +UC3) Write record to long DN app stream using saflogger tool. + +The implementation was split into following parts: +1) Update saflogger tool - add one more option `-f` +2) Update LOG agent (API) to support Long DN +3) Update LOG service to support Long DN +4) Create test cases + +Besides, README file and OpenSAF_LOG_PR.odt have to be updated. + + +II) IMPLEMENTATION (#1315) +============================== + +1) Update saflogger tool - Add One More Option `-f` +------------------------------------------------- +`-f` option is only applicable for application stream. Means it is only valid +when comes together with option `-a`. If no `-f` is provided, default behavior is maintained. + +Why need to add new option `-f` to saflogger tool? +When long DN is supported, user is able to put long DN name after option `-a`, and saflogger tool will +use that long DN for log file name of that app stream. In that case, the log file name will be over 256 characters in length. +As the result, logsv could get failed to create such long file name (most Unix system supports file name length up to 255 characters). + + +2) Update LOG Agent (API) to Support Long DN +--------------------------------------------- +All internal SaNameT will be replaced by SaConstStringT and functions handling extended SaNameT are used. + +One point needs to be noticed is that, with extended SaNameT, data size could be up to 2048 bytes (not limited to 256 bytes any more). +As the result, several condition checking for max length size against 256 bytes will be updated to 2048 bytes (kOsafMaxDnLength). +So, when supported long DN client (e.g: log client running on OpenSAF 5.1 or newer versions) sends an record containing long DN +(e.g: `notificationObject` length > 256 bytes) to active Log service not support long DN (e.g: active log running on OpenSAF 5.0 +or older versions), that log client will get `SA_AIS_ERR_TRY_AGAIN` always and make cause the log client hang. +There is no problem with the opposite case (non-support long DN do communicate with supported long DN). + + +3) Update LOG Service to Support Long DN +---------------------------------------- +In original code, logsv used NCS PATRICIA TREE as an database to hold all existing LOG streams in system, +and taking stream DN as the keyword for searching/adding/deleting tree elements. +NCS PATRICIA TREE has a limitation with keyword size. It is only supported the key size up to 600 bytes. +With long DN, stream DN could be up to 2024 bytes (kOsafMaxDnLength), that tree is no longer valid. + +Besides, logsv is providing other database named `stream_array` which is used to hold all LOG existing streams. +When there is any new stream created, `log_stream_t` holding information of that stream, will be added to that database +and when the stream is closed and no client connects to that stream, it will be removed from the database. +That database is a two-dimensional array with data format: + { + { <streamId1>, <pointer to `log_stream_t`> }, + { <streamId2>, <pointer to `log_stream_t`> }, + ... + } + +Logsv is able to query below infos from `stream_array` that logsv used to do so based on NCS PATRICIA TREE: +- Is there any current log stream with specific DN in system? +- Or what are the current log existing streams in system? +Therefore, NCS PATRICIA TREE can be removed from logsv code. `stream_array` database can play the same role as NCS_PATRICIA_TREE. + +More on `stream_array` database. All rooms in `stream_array` is clean/reset at startup. +First three rooms are reserved for well-known streams. +At the moment (OpenSAF 5.1), there are total 67 rooms (64 for app streams + 3 for well-known streams). +Adding/deleting/searching items to/from this database is fast. + +In addition to above change, internal SaNameT will be replaced by SaConstStringT or C++ strings and functions handling extended SaNameT are used. + +NOTES: +If active node is OpenSAF 5.1 or newer communicate with older versions such as OpenSAF 5.0 (not support Long DN), +then if there is operation on creating app stream with Long DN, standby node will be crashed. +This will happen because active node sends checkpoint data to standby node, and there is copying data operation (strcpy) +to SaNameT type. Make the data is overflowed. strcpy() should not be used anywhere in code, but strncpy() instead. + +To avoid this happens, two options: +a) During upgrade, make sure there is no long DN operation run until the upgrade is finished. +b) Raise one ticket to fix all places using strcpy() + + +4) Create Test Cases +----------------------------- +New test suite - suite #13 with ten test cases were created to cover minimum requirement described at `GENERAL` section. +Including five normal use cases and five abnormal use cases. + +Each test cases is done with following frame: +a) Backup data such as current IMM attribute values, so that it can be restored back after test run. +b) Set up environment such as enabling long DN support in IMM, change log stream attribute values +c) Write log record containing long DN or creating streams with Long DN. +d) Verify the data if it contains what we expect to have such as log file contains long DN at specific token or not. +e) Close all opened handles +f) Restore the data back to original values. + +At verifying step, if the environment variable `LOGTEST_ENABLE_STDOUT` is set, user will be able to see +the verifying data such as long notifyingObj at specific log file name. +And when running the test suite #13, user does not have to to take care how to set up environment +for long DN testing, all precondition are set to make sure the long DN work. + +Users can refer to these test cases to see how to pass long DN data to LOG APIs, +and what are precondition settings for using extended SaNameT. +The tests are located in the file `~/tests/logsv/tet_log_longDN.c` + +Besides, some other tests/check have been done: +a) Valgrind check +b) Upgrade/downgrade test +c) Cppcheck run + + +III. REFERENCES +======================= + +1) OpenSAF_Extensions_PR.odt + ------------------------------------------------------------------------------ Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San Francisco, CA to explore cutting-edge tech and listen to tech luminaries present their vision of the future. This family event has something for everyone, including kids. Get more information and register today. http://sdm.link/attshape _______________________________________________ Opensaf-devel mailing list Opensaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensaf-devel
