ceph/src/jaegertracing/thrift/lib/cpp/README.md

   1 Thrift C++ Software Library
   2
   3 # License
   4
   5 Licensed to the Apache Software Foundation (ASF) under one
   6 or more contributor license agreements. See the NOTICE file
   7 distributed with this work for additional information
   8 regarding copyright ownership. The ASF licenses this file
   9 to you under the Apache License, Version 2.0 (the
  10 "License"); you may not use this file except in compliance
  11 with the License. You may obtain a copy of the License at
  12
  13   http://www.apache.org/licenses/LICENSE-2.0
  14
  15 Unless required by applicable law or agreed to in writing,
  16 software distributed under the License is distributed on an
  17 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18 KIND, either express or implied. See the License for the
  19 specific language governing permissions and limitations
  20 under the License.
  21
  22 # Using Thrift with C++
  23
  24 The Thrift C++ libraries are built using the GNU tools. Follow the instructions
  25 in the top-level README.md
  26
  27 In case you do not want to open another README.md file, do this thrift src:
  28
  29     ./bootstrap.sh
  30     ./configure (--with-boost=/usr/local)
  31     make
  32     sudo make install
  33
  34 Thrift is divided into two libraries.
  35
  36 * libthrift - The core Thrift library contains all the core Thrift code.  This requires
  37   openssl, pthreads, and librt.
  38
  39 * libthriftnb - This library contains the Thrift nonblocking server, which uses libevent.
  40   To link this library you will also need to link libevent.
  41
  42 ## Linking Against Thrift
  43
  44 After you build and install Thrift the libraries are installed to
  45 /usr/local/lib by default. Make sure this is in your LDPATH.
  46
  47 On Linux, the best way to do this is to ensure that /usr/local/lib is in
  48 your /etc/ld.so.conf and then run /sbin/ldconfig.
  49
  50 Depending upon whether you are linking dynamically or statically and how
  51 your build environment it set up, you may need to include additional
  52 libraries when linking against thrift, such as librt and/or libpthread. If
  53 you are using libthriftnb you will also need libevent.
  54
  55 ## Dependencies
  56
  57 C++11 is required at a minimum.  C++03/C++98 are not supported after version 0.12.0.
  58
  59 Boost is required to run the C++ unit tests.  It is not necessary to link against
  60 the runtime library.
  61
  62 libevent (for libthriftnb only) - most linux distributions have dev packages for this:
  63 http://monkey.org/~provos/libevent/
  64
  65 # Using Thrift with C++ on Windows
  66
  67 Both the autoconf and cmake build systems are able to automatically detect many
  68 system configurations without the need to specify library locations, however if
  69 you run into problems or want to redirect thrift to build and link against your
  70 own provided third party libraries:
  71
  72 BOOST_ROOT : For boost, e.g. D:\boost_1_55_0
  73 OPENSSL_ROOT_DIR : For OpenSSL, e.g. D:\OpenSSL-Win32
  74
  75 only required by libthriftnb:
  76
  77 LIBEVENT_ROOT_DIR : For Libevent e.g. D:\libevent-2.0.21-stable
  78
  79 See /3rdparty.user for more details.
  80
  81 The same linking guidelines described above for libthriftnb apply to windows as well.
  82
  83 ## Linking Against Thrift
  84
  85 You need to link your project that uses thrift against all the thrift
  86 dependencies; in the case of libthrift, openssl, pthreads, and librt and for
  87 libthriftnb, libevent.
  88
  89 In the project properties you must also set HAVE_CONFIG_H as force include
  90 the config header: "windows/config.h"
  91
  92 ## Dependencies
  93
  94 libevent (for libthriftnb only)
  95 http://monkey.org/~provos/libevent/
  96
  97 ## Windows version compatibility
  98
  99 The Thrift library targets Windows 7 or latter versions. The supports for windows XP and Vista are avaiable until 0.12.0.
 100
 101 ## Named Pipes
 102
 103 Named Pipe transport has been added in the TPipe and TPipeServer classes. This
 104 is currently Windows-only. Named pipe transport for *NIX has not been
 105 implemented. Domain sockets are a better choice for local IPC under non-Windows
 106 OS's. *NIX named pipes only support 1:1 client-server connection.
 107
 108 # Thrift/SSL
 109
 110 ## Scope
 111
 112 This SSL only supports blocking mode socket I/O. It can only be used with
 113 TSimpleServer, TThreadedServer, and TThreadPoolServer.
 114
 115 ## Implementation
 116
 117 There are two main classes TSSLSocketFactory and TSSLSocket. Instances of
 118 TSSLSocket are always created from TSSLSocketFactory.
 119
 120 ## How to use SSL APIs
 121
 122 See the TestClient.cpp and TestServer.cpp files for examples.
 123
 124 ### AccessManager (certificate validation)
 125
 126 An example of certificate validation can be found in TestServer.cpp.
 127
 128 AccessManager defines a callback interface. It has three callback methods:
 129
 130 (a) Decision verify(const sockaddr_storage& sa);
 131
 132 (b) Decision verify(const string& host, const char* name, int size);
 133
 134 (c) Decision verify(const sockaddr_storage& sa, const char* data, int size);
 135
 136 After SSL handshake completes, additional checks are conducted. Application
 137 is given the chance to decide whether or not to continue the conversation
 138 with the remote. Application is queried through the above three "verify"
 139 method. They are called at different points of the verification process.
 140
 141 Decisions can be one of ALLOW, DENY, and SKIP. ALLOW and DENY means the
 142 conversation should be continued or disconnected, respectively. ALLOW and
 143 DENY decision stops the verification process. SKIP means there's no decision
 144 based on the given input, continue the verification process.
 145
 146 First, (a) is called with the remote IP. It is called once at the beginning.
 147 "sa" is the IP address of the remote peer.
 148
 149 Then, the certificate of remote peer is loaded. SubjectAltName extensions
 150 are extracted and sent to application for verification. When a DNS
 151 subjectAltName field is extracted, (b) is called. When an IP subjectAltName
 152 field is extracted, (c) is called.
 153
 154 The "host" in (b) is the value from TSocket::getHost() if this is a client
 155 side socket, or TSocket::getPeerHost() if this is a server side socket. The
 156 reason is client side socket initiates the connection. TSocket::getHost()
 157 is the remote host name. On server side, the remote host name is unknown
 158 unless it's retrieved through TSocket::getPeerHost(). Either way, "host"
 159 should be the remote host name. Keep in mind, if TSocket::getPeerHost()
 160 failed, it would return the remote host name in numeric format.
 161
 162 If all subjectAltName extensions were "skipped", the common name field would
 163 be checked. It is sent to application through (c), where "sa" is the remote
 164 IP address. "data" is the IP address extracted from subjectAltName IP
 165 extension, and "size" is the length of the extension data.
 166
 167 If any of the above "verify" methods returned a decision ALLOW or DENY, the
 168 verification process would be stopped.
 169
 170 If any of the above "verify" methods returned SKIP, that decision would be
 171 ignored and the verification process would move on till the last item is
 172 examined. At that point, if there's still no decision, the connection is
 173 terminated.
 174
 175 Thread safety, an access manager should not store state information if it's
 176 to be used by many SSL sockets.
 177
 178 ## SIGPIPE signal
 179
 180 Applications running OpenSSL over network connections may crash if SIGPIPE
 181 is not ignored. This happens when they receive a connection reset by remote
 182 peer exception, which somehow triggers a SIGPIPE signal. If not handled,
 183 this signal would kill the application.
 184
 185 ## How to run test client/server in SSL mode
 186
 187 The server and client expects the followings from the directory /test/
 188
 189 - keys/server.crt
 190 - keys/server.key
 191 - keys/CA.pem
 192
 193 The file names are hard coded in the source code. You need to create these
 194 certificates before you can run the test code in SSL mode. Make sure at least
 195 one of the followings is included in "keys/server.crt",
 196
 197 - subjectAltName, DNS localhost
 198 - subjectAltName, IP  127.0.0.1
 199 - common name,    localhost
 200
 201 Run within /test/ folder,
 202
 203          ./cpp/TestServer --ssl &
 204          ./cpp/TestClient --ssl
 205
 206 If "-h <host>" is used to run client, the above "localhost" in the above
 207 keys/server.crt has to be replaced with that host name.
 208
 209 ## TSSLSocketFactory::randomize()
 210
 211 The default implementation of OpenSSLSocketFactory::randomize() simply calls
 212 OpenSSL's RAND_poll() when OpenSSL library is first initialized.
 213
 214 The PRNG seed is key to the application security. This method should be
 215 overridden if it's not strong enough for you.
 216
 217 # Deprecations
 218
 219 ## 0.12.0
 220
 221 Support for C++03/C++98 was deprecated.
 222 Support for Boost at runtime was deprecated.
 223
 224 # Breaking Changes
 225
 226 ## 1.0.0
 227
 228 THRIFT-4720:
 229 The classes Monitor and TimerManager now use std::chrono::milliseconds for timeout, the methods and functions involving THRIFT_TIMESPEC and timeval have been removed, the related tests have been modified.
 230
 231 Support for Windows XP/Vista has been dropped.
 232
 233 Support for C++03/C++98 has been dropped.  Use version 0.12.0 to support that
 234 language level.  As a consequence, boost is no longer required as a runtime
 235 library depenedency, but is is still required to build the runtime library
 236 and to run the unit tests.  We will work towards removing boost as a
 237 build dependency for folks who just want to build the runtime and not
 238 run the tests.  This means the header thrift/stdcxx.h has been removed and
 239 anything that relied on it has been changed to directly use C++11 concepts.
 240
 241 THRIFT-4730:
 242 The classes BoostThreadFactory, PosixThreadFactory, StdThreadFactory, and
 243 PlatformThreadFactory have been removed, and we will use a ThreadFactory
 244 based on C++11 (essentially StdThreadFactory was renamed ThreadFactory).
 245
 246 THRIFT-4732:
 247 The CMake build options WITH_SHARED_LIBS and WITH_STATIC_LIBS are deprecated.
 248 The project no longer performs a side-by-side static and shared build; you
 249 tell CMake through BUILD_SHARED_LIBS whether to make shared or static
 250 libraries now.  This is CMake standard behavior.
 251
 252 THRIFT-4735:
 253 Qt4 support was removed.
 254
 255 THRIFT-4762:
 256 Added `const` specifier to `TTransport::getOrigin()`. This changes its function signature.
 257 It's recommended to add the `override` specifier in implementations derived from `TTransport`.
 258
 259 ## 0.11.0
 260
 261 Older versions of thrift depended on the <boost/smart_ptr.hpp> classes which
 262 were used in thrift headers to define interfaces.  Thrift now detects C++11
 263 at build time and will prefer to use <memory> classes from C++11 instead.
 264 You can force the library to build with boost memory classes by defining the
 265 preprocessor macro `FORCE_BOOST_SMART_PTR`.  (THRIFT-2221)
 266
 267 In the pthread mutex implementation, the contention profiling code was enabled
 268 by default in all builds.  This changed to be disabled by default.  (THRIFT-4151)
 269
 270 In older releases, if a TSSLSocketFactory's lifetime was not at least as long
 271 as the TSSLSockets it created, we silently reverted openssl to unsafe multithread behavior
 272 and so the results were undefined.  Changes were made in 0.11.0 that cause either an
 273 assertion or a core instead of undefined behavior.  The lifetime of a TSSLSocketFactory
 274 *must* be longer than any TSSLSocket that it creates, otherwise openssl will be cleaned
 275 up too early.  If the static boolean is set to disable openssl initialization and
 276 cleanup and leave it up to the consuming application, this requirement is not needed.
 277 (THRIFT-4164)
 278