kinetic-c  v0.12.0
Seagate Kinetic Protocol Client Library for C
README.md
Go to the documentation of this file.
1 [![Build Status](http://travis-ci.org/Seagate/kinetic-c.png?branch=master)](http://travis-ci.org/Seagate/kinetic-c)
2 Kinetic C Client Library
3 ========================
4 The [Github kinetic-c Git repository](https://github.com/Seagate/kinetic-c) contains code for producing Kinetic C clients for interacting with Kinetic storage object-based storage. The library uses the cross-platform Seagate Kinetic protocol for standardizing interaces between the Java simulator and Kinetic Device storage clusters.
5 
6 Reference code is included as part of the [kinetic-c client library test utility (`kinetic-c-util`)](src/utility), which builds and links against the installed `kinetic-c-client` static library. [Additional examples](src/examples) are included for the various types of I/O operations (e.g. blocking/non-blocking, single/multi-threaded). See below for more details.
7 
8 The [project Makefile](Makefile) can be used as a reference for developing a Makefile-based project for building for a custom Kinetic Storage C client driver and/or a high-level C library.
9 
10 Kinetic Protocol Support
11 ------------------------
12 Built using:
13 
14 * [Kinetic Protocol v3.0.5](https://github.com/Seagate/kinetic-protocol/tree/3.0.5)
15 * [ProtoBuf-C v1.1.0](https://github.com/protobuf-c/protobuf-c)
16 * [Google ProtoBuf v2.6.0](https://developers.google.com/protocol-buffers/docs/downloads)
17 
18 Prerequisites
19 -------------
20 
21 * [Open SSL](https://www.openssl.org/) for security and encryption
22  * Installation (if you don't already have OpenSSL installed)
23  * Linux (using apt-get)
24  * `> sudo apt-get install openssl`
25  * Linux (using yum)
26  * `> sudo yum install openssl`
27  * OSX (using [Homebrew](http://brew.sh/))
28  * `> brew install openssl`
29 * [json-c](https://github.com/json-c/json-c) for JSON-formatted ACL definition files
30  * Installation
31  * via package manager
32  * Linux (using apt-get)
33  * `> sudo apt-get install json-c`
34  * Linux (using yum)
35  * `> sudo yum install json-c`
36  * OSX (using [Homebrew](http://brew.sh/))
37  * `> brew install openssl`
38  * via Git submodule (from bundled source)
39  * `> make json`
40  * `> sudo make install_json`
41 
42 A release of OpenSSL that provides TLS 1.1 or newer is required.
43 
44 If the OpenSSL installation is not found, the `OPENSSL_PATH` environment
45 variable may need to be set to its base path, e.g.
46 `export OPENSSL_PATH=/usr/local/openssl/1.0.1k/`.
47 
48 Getting Started
49 ---------------
50 
51 **Clone the repo**
52 
53  > git clone --recursive https://github.com/seagate/kinetic-c.git
54  > cd kinetic-c
55 
56 **Update to the latest version (previously cloned)**
57 
58  > git pull
59  > make config # ensures all git submodules are up to date
60 
61 **Build and install static library**
62 
63  > make
64  > sudo make install
65 
66 **Clean and uninstall any old versions**
67 
68  > make clean
69  > sudo make uninstall
70 
71 **Build example utility and run tests against Kinetic Device simulator**
72 
73  > make start_sims # starts bundled kinetic-java simulators for testing
74  > make all # this is what Travis-CI build does does for regression testing
75 
76 API Documentation
77 =================
78 
79 [Kinetic-C API Documentation](http://seagate.github.io/kinetic-c/) (generated with Doxygen)
80 * [Kinetic-C API](http://seagate.github.io/kinetic-c/kinetic__client_8h.html)
81 * [Kinetic-C types](http://seagate.github.io/kinetic-c/kinetic__types_8h.html)
82 * [ByteArray API](http://seagate.github.io/kinetic-c/byte__array_8h.html)
83  * The ByteArray and ByteBuffer types are used for exchanging variable length byte-arrays with kinetic-c
84  * e.g. object keys, object value data, etc.
85 
86 **NOTE: Configuration structures `KineticClientConfig` and `KineticSessionConfig` should be initialized per C99 struct initialization or memset to 0 prior to use in order to ensure forward/backward compatibility upon changes to these structure definitions!**
87 
88 Client Test Utility
89 ===========================
90 
91 Code examples are included for reference as part of a test utility. The source code for the utility is used to build both a static and dynamically linked verion of the kinetic-c-client library.
92 
93 * `kinetic-c-util` builds/links against Kinetic C static library (.a)
94 * `kinetic-c-util.x.y.z` builds/links against Kinetic C dynamic library (.so)
95 
96 Usage
97 ----------
98 
99  $ cd bin
100  $ ./kinetic-c-util --help
101  Usage: ./bin/kinetic-c-util --<cmd> [options...]
102  ./bin/kinetic-c-util --help
103  ./bin/kinetic-c-util --noop [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
104  ./bin/kinetic-c-util --put --key <key> --value <value> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
105  ./bin/kinetic-c-util --get --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
106  ./bin/kinetic-c-util --getnext --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
107  ./bin/kinetic-c-util --getprevious --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
108  ./bin/kinetic-c-util --delete --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
109  ./bin/kinetic-c-util --getlog --logtype <utilizations|temperatures|capacities|configuration|statistics|messages|limits> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
110  ./bin/kinetic-c-util --getdevicespecificlog --devicelogname <name|ID> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
111  ./bin/kinetic-c-util --setclusterversion --newclusterversion <newclusterversion> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
112  ./bin/kinetic-c-util --seterasepin --pin <oldpin> --newpin <newerasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
113  ./bin/kinetic-c-util --instanterase --pin <erasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
114  ./bin/kinetic-c-util --secureerase --pin <erasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
115  ./bin/kinetic-c-util --setlockpin --pin <oldpin>> <--newpin <newpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
116  ./bin/kinetic-c-util --lockdevice --pin <lockpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
117  ./bin/kinetic-c-util --unlockdevice --pin <lockpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
118  ./bin/kinetic-c-util --setacl --file <acl_json_file> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
119  ./bin/kinetic-c-util --updatefirmware --file <file> --pin <pin> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
120 
121 Kinetic C Client I/O Examples
122 =============================
123 
124 * [`blocking_put_get`](src/examples/blocking_put_get.c) - Blocking put w/get.
125 * [`blocking_put_delete`](src/examples/blocking_put_delete.c) - Blocking put w/delete.
126 * [`put_nonblocking`](src/examples/put_nonblocking.c) - Single thread, single connection, nonblocking put operation.
127 * [`get_nonblocking`](src/examples/get_nonblocking.c) - Single thread, single connection, nonblocking get operation.
128 * [`get_key_range`](src/examples/get_key_range.c) - Query a range of keys from a device.
129 * [`write_file_blocking`](src/examples/write_file_blocking.c) - Single thread, single connection, blocking operation.
130 * [`write_file_blocking_threads`](src/examples/write_file_blocking_threads.c) - Multiple threads, single connection, blocking operations.
131 * [`write_file_nonblocking`](src/examples/write_file_nonblocking.c) - Single thread, single connection, multiple non-blocking operations
132 * [`write_file_blocking_threads`](src/examples/write_file_blocking_threads.c) - Multiple threads, single connection, multiple non-blocking operations.