README.md
1# mdata-client
2
3This repository contains metadata retrieval and manipulation tools for use
4within guests of the SmartOS (and SDC) hypervisor. These guests may be either
5SmartOS Zones or KVM virtual machines.
6
7This repository is part of the Joyent SmartDataCenter project (SDC). For
8contribution guidelines, issues, and general documentation, visit the main
9[SDC](http://github.com/joyent/sdc) project page.
10
11# Commands
12
13There are four commands provided in this consolidation:
14
15* [mdata-list(1M)][mdata_list]; list custom metadata keys in the metadata store
16* [mdata-get(1M)][mdata_get]; get the value of a particular metadata key
17* [mdata-put(1M)][mdata_put]; set the value of a particular metadata key
18* [mdata-delete(1M)][mdata_delete]; remove a metadata key
19
20Manual pages for these tools are available in this repository, and are
21generally shipped with the OS (in the case of SmartOS) or in the package (e.g.
22[for Ubuntu][launchpad_pkg]). They are also viewable on the web at the links
23above.
24
25# Protocol and Transport
26
27The Joyent Metadata Protocol [is documented online][protocol]. The programs in
28this repository are clients that communicate using this protocol. The SmartOS
29(or SmartDataCenter) hypervisor provides a [common set][datadict] of supported
30base metadata keys for guests to consume, as well as the ability to support
31arbitrary additional user-provided metadata.
32
33In a SmartOS container/zone guest, a UNIX domain socket is used to communicate
34with the metadata server running in the hypervisor. In a KVM guest, such as a
35Linux virtual machine, the client tools will make use of the second serial port
36(e.g. `ttyb`, or `COM2`) to communicate with the hypervisor.
37
38# OS Support
39
40The tools currently build and function on SmartOS and various Linux
41distributions. Support for other operating systems, such as \*BSD or Windows,
42is absolutely welcome.
43
44## License
45
46MIT (See _LICENSE_.)
47
48[mdata_docs]: http://eng.joyent.com/mdata/
49[protocol]: http://eng.joyent.com/mdata/protocol.html
50[datadict]: http://eng.joyent.com/mdata/datadict.html
51[mdata_get]: http://smartos.org/man/1M/mdata-get
52[mdata_delete]: http://smartos.org/man/1M/mdata-delete
53[mdata_put]: http://smartos.org/man/1M/mdata-put
54[mdata_list]: http://smartos.org/man/1M/mdata-list
55[launchpad_pkg]: https://launchpad.net/ubuntu/+source/joyent-mdata-client
56