amps-python-client 5.3.4.1__zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (550) hide show
  1. amps-python-client-5.3.4.1/HISTORY +7 -0
  2. amps-python-client-5.3.4.1/LICENSE +157 -0
  3. amps-python-client-5.3.4.1/PKG-INFO +112 -0
  4. amps-python-client-5.3.4.1/README.md +96 -0
  5. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/ack-messages.doctree +0 -0
  6. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/content-messages.doctree +0 -0
  7. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/intro.doctree +0 -0
  8. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/logon.doctree +0 -0
  9. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/protocol-reference.doctree +0 -0
  10. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/publishing.doctree +0 -0
  11. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/query-delimiters.doctree +0 -0
  12. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/query-subscribe.doctree +0 -0
  13. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/removing.doctree +0 -0
  14. amps-python-client-5.3.4.1/docs/command-reference/doctrees/chapters/utilities.doctree +0 -0
  15. amps-python-client-5.3.4.1/docs/command-reference/doctrees/environment.pickle +0 -0
  16. amps-python-client-5.3.4.1/docs/command-reference/doctrees/index.doctree +0 -0
  17. amps-python-client-5.3.4.1/docs/command-reference/html/.buildinfo +4 -0
  18. amps-python-client-5.3.4.1/docs/command-reference/html/_images/caution.svg +25 -0
  19. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/ack-messages.rst.txt +32 -0
  20. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/content-messages.rst.txt +27 -0
  21. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/intro.rst.txt +43 -0
  22. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/logon.rst.txt +231 -0
  23. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/protocol-reference.rst.txt +1474 -0
  24. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/publishing.rst.txt +25 -0
  25. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/query-delimiters.rst.txt +12 -0
  26. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/query-subscribe.rst.txt +23 -0
  27. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/removing.rst.txt +6 -0
  28. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/utilities.rst.txt +13 -0
  29. amps-python-client-5.3.4.1/docs/command-reference/html/_sources/index.rst.txt +56 -0
  30. amps-python-client-5.3.4.1/docs/command-reference/html/_static/ajax-loader.gif +0 -0
  31. amps-python-client-5.3.4.1/docs/command-reference/html/_static/alabaster.css +699 -0
  32. amps-python-client-5.3.4.1/docs/command-reference/html/_static/basic.css +632 -0
  33. amps-python-client-5.3.4.1/docs/command-reference/html/_static/comment-bright.png +0 -0
  34. amps-python-client-5.3.4.1/docs/command-reference/html/_static/comment-close.png +0 -0
  35. amps-python-client-5.3.4.1/docs/command-reference/html/_static/comment.png +0 -0
  36. amps-python-client-5.3.4.1/docs/command-reference/html/_static/custom.css +192 -0
  37. amps-python-client-5.3.4.1/docs/command-reference/html/_static/custom.css.backup +161 -0
  38. amps-python-client-5.3.4.1/docs/command-reference/html/_static/doctools.js +287 -0
  39. amps-python-client-5.3.4.1/docs/command-reference/html/_static/down-pressed.png +0 -0
  40. amps-python-client-5.3.4.1/docs/command-reference/html/_static/down.png +0 -0
  41. amps-python-client-5.3.4.1/docs/command-reference/html/_static/file.png +0 -0
  42. amps-python-client-5.3.4.1/docs/command-reference/html/_static/flag_logo.png +0 -0
  43. amps-python-client-5.3.4.1/docs/command-reference/html/_static/flag_logo.svg +153 -0
  44. amps-python-client-5.3.4.1/docs/command-reference/html/_static/jquery-3.1.0.js +10074 -0
  45. amps-python-client-5.3.4.1/docs/command-reference/html/_static/jquery.js +4 -0
  46. amps-python-client-5.3.4.1/docs/command-reference/html/_static/minus.png +0 -0
  47. amps-python-client-5.3.4.1/docs/command-reference/html/_static/plus.png +0 -0
  48. amps-python-client-5.3.4.1/docs/command-reference/html/_static/pygments.css +74 -0
  49. amps-python-client-5.3.4.1/docs/command-reference/html/_static/searchtools.js +758 -0
  50. amps-python-client-5.3.4.1/docs/command-reference/html/_static/underscore-1.3.1.js +999 -0
  51. amps-python-client-5.3.4.1/docs/command-reference/html/_static/underscore.js +31 -0
  52. amps-python-client-5.3.4.1/docs/command-reference/html/_static/up-pressed.png +0 -0
  53. amps-python-client-5.3.4.1/docs/command-reference/html/_static/up.png +0 -0
  54. amps-python-client-5.3.4.1/docs/command-reference/html/_static/websupport.js +808 -0
  55. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/ack-messages.html +417 -0
  56. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/content-messages.html +417 -0
  57. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/intro.html +126 -0
  58. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/logon.html +295 -0
  59. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/protocol-reference.html +1190 -0
  60. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/publishing.html +436 -0
  61. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/query-delimiters.html +173 -0
  62. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/query-subscribe.html +2123 -0
  63. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/removing.html +299 -0
  64. amps-python-client-5.3.4.1/docs/command-reference/html/chapters/utilities.html +287 -0
  65. amps-python-client-5.3.4.1/docs/command-reference/html/genindex.html +97 -0
  66. amps-python-client-5.3.4.1/docs/command-reference/html/index.html +138 -0
  67. amps-python-client-5.3.4.1/docs/command-reference/html/objects.inv +0 -0
  68. amps-python-client-5.3.4.1/docs/command-reference/html/search.html +107 -0
  69. amps-python-client-5.3.4.1/docs/command-reference/html/searchindex.js +1 -0
  70. amps-python-client-5.3.4.1/docs/html/.buildinfo +4 -0
  71. amps-python-client-5.3.4.1/docs/html/_sources/code.rst.txt +6 -0
  72. amps-python-client-5.3.4.1/docs/html/_sources/index.rst.txt +29 -0
  73. amps-python-client-5.3.4.1/docs/html/_static/ajax-loader.gif +0 -0
  74. amps-python-client-5.3.4.1/docs/html/_static/basic.css +632 -0
  75. amps-python-client-5.3.4.1/docs/html/_static/classic.css +261 -0
  76. amps-python-client-5.3.4.1/docs/html/_static/comment-bright.png +0 -0
  77. amps-python-client-5.3.4.1/docs/html/_static/comment-close.png +0 -0
  78. amps-python-client-5.3.4.1/docs/html/_static/comment.png +0 -0
  79. amps-python-client-5.3.4.1/docs/html/_static/default.css +1 -0
  80. amps-python-client-5.3.4.1/docs/html/_static/doctools.js +287 -0
  81. amps-python-client-5.3.4.1/docs/html/_static/down-pressed.png +0 -0
  82. amps-python-client-5.3.4.1/docs/html/_static/down.png +0 -0
  83. amps-python-client-5.3.4.1/docs/html/_static/file.png +0 -0
  84. amps-python-client-5.3.4.1/docs/html/_static/jquery-3.1.0.js +10074 -0
  85. amps-python-client-5.3.4.1/docs/html/_static/jquery.js +4 -0
  86. amps-python-client-5.3.4.1/docs/html/_static/minus.png +0 -0
  87. amps-python-client-5.3.4.1/docs/html/_static/plus.png +0 -0
  88. amps-python-client-5.3.4.1/docs/html/_static/pygments.css +74 -0
  89. amps-python-client-5.3.4.1/docs/html/_static/searchtools.js +758 -0
  90. amps-python-client-5.3.4.1/docs/html/_static/sidebar.js +159 -0
  91. amps-python-client-5.3.4.1/docs/html/_static/underscore-1.3.1.js +999 -0
  92. amps-python-client-5.3.4.1/docs/html/_static/underscore.js +31 -0
  93. amps-python-client-5.3.4.1/docs/html/_static/up-pressed.png +0 -0
  94. amps-python-client-5.3.4.1/docs/html/_static/up.png +0 -0
  95. amps-python-client-5.3.4.1/docs/html/_static/websupport.js +808 -0
  96. amps-python-client-5.3.4.1/docs/html/code.html +6503 -0
  97. amps-python-client-5.3.4.1/docs/html/genindex.html +1361 -0
  98. amps-python-client-5.3.4.1/docs/html/index.html +131 -0
  99. amps-python-client-5.3.4.1/docs/html/objects.inv +0 -0
  100. amps-python-client-5.3.4.1/docs/html/py-modindex.html +111 -0
  101. amps-python-client-5.3.4.1/docs/html/search.html +107 -0
  102. amps-python-client-5.3.4.1/docs/html/searchindex.js +1 -0
  103. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/advanced-topics.doctree +0 -0
  104. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/cpp-compiler-list.doctree +0 -0
  105. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/cpp-feature-table.doctree +0 -0
  106. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/creating-commands.doctree +0 -0
  107. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/deltas.doctree +0 -0
  108. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/error-handling.doctree +0 -0
  109. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/exceptions.doctree +0 -0
  110. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/first-program.doctree +0 -0
  111. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/high-availability.doctree +0 -0
  112. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/installing.doctree +0 -0
  113. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/introduction.doctree +0 -0
  114. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/moving-from-python-lite.doctree +0 -0
  115. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/performance-tips.doctree +0 -0
  116. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/queues.doctree +0 -0
  117. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/sow.doctree +0 -0
  118. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/subscriptions.doctree +0 -0
  119. amps-python-client-5.3.4.1/docs/python/doctrees/chapters/utilities.doctree +0 -0
  120. amps-python-client-5.3.4.1/docs/python/doctrees/environment.pickle +0 -0
  121. amps-python-client-5.3.4.1/docs/python/doctrees/index.doctree +0 -0
  122. amps-python-client-5.3.4.1/docs/python/html/.buildinfo +4 -0
  123. amps-python-client-5.3.4.1/docs/python/html/_images/caution.png +0 -0
  124. amps-python-client-5.3.4.1/docs/python/html/_images/caution.svg +25 -0
  125. amps-python-client-5.3.4.1/docs/python/html/_images/connection_string.svg +461 -0
  126. amps-python-client-5.3.4.1/docs/python/html/_images/important.png +0 -0
  127. amps-python-client-5.3.4.1/docs/python/html/_images/important.svg +25 -0
  128. amps-python-client-5.3.4.1/docs/python/html/_images/tip.png +0 -0
  129. amps-python-client-5.3.4.1/docs/python/html/_images/tip.svg +31 -0
  130. amps-python-client-5.3.4.1/docs/python/html/_images/warning.png +0 -0
  131. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/advanced-topics.rst.txt +398 -0
  132. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/cpp-compiler-list.rst.txt +6 -0
  133. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/cpp-feature-table.rst.txt +26 -0
  134. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/creating-commands.rst.txt +159 -0
  135. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/deltas.rst.txt +79 -0
  136. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/error-handling.rst.txt +482 -0
  137. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/exceptions.rst.txt +128 -0
  138. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/first-program.rst.txt +142 -0
  139. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/high-availability.rst.txt +876 -0
  140. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/installing.rst.txt +184 -0
  141. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/introduction.rst.txt +50 -0
  142. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/moving-from-python-lite.rst.txt +32 -0
  143. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/performance-tips.rst.txt +434 -0
  144. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/queues.rst.txt +282 -0
  145. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/sow.rst.txt +292 -0
  146. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/subscriptions.rst.txt +374 -0
  147. amps-python-client-5.3.4.1/docs/python/html/_sources/chapters/utilities.rst.txt +214 -0
  148. amps-python-client-5.3.4.1/docs/python/html/_sources/index.rst.txt +44 -0
  149. amps-python-client-5.3.4.1/docs/python/html/_static/ajax-loader.gif +0 -0
  150. amps-python-client-5.3.4.1/docs/python/html/_static/alabaster.css +699 -0
  151. amps-python-client-5.3.4.1/docs/python/html/_static/basic.css +632 -0
  152. amps-python-client-5.3.4.1/docs/python/html/_static/comment-bright.png +0 -0
  153. amps-python-client-5.3.4.1/docs/python/html/_static/comment-close.png +0 -0
  154. amps-python-client-5.3.4.1/docs/python/html/_static/comment.png +0 -0
  155. amps-python-client-5.3.4.1/docs/python/html/_static/custom.css +192 -0
  156. amps-python-client-5.3.4.1/docs/python/html/_static/custom.css.backup +161 -0
  157. amps-python-client-5.3.4.1/docs/python/html/_static/doctools.js +287 -0
  158. amps-python-client-5.3.4.1/docs/python/html/_static/down-pressed.png +0 -0
  159. amps-python-client-5.3.4.1/docs/python/html/_static/down.png +0 -0
  160. amps-python-client-5.3.4.1/docs/python/html/_static/file.png +0 -0
  161. amps-python-client-5.3.4.1/docs/python/html/_static/flag_logo.png +0 -0
  162. amps-python-client-5.3.4.1/docs/python/html/_static/flag_logo.svg +153 -0
  163. amps-python-client-5.3.4.1/docs/python/html/_static/jquery-3.1.0.js +10074 -0
  164. amps-python-client-5.3.4.1/docs/python/html/_static/jquery.js +4 -0
  165. amps-python-client-5.3.4.1/docs/python/html/_static/minus.png +0 -0
  166. amps-python-client-5.3.4.1/docs/python/html/_static/plus.png +0 -0
  167. amps-python-client-5.3.4.1/docs/python/html/_static/pygments.css +74 -0
  168. amps-python-client-5.3.4.1/docs/python/html/_static/searchtools.js +758 -0
  169. amps-python-client-5.3.4.1/docs/python/html/_static/underscore-1.3.1.js +999 -0
  170. amps-python-client-5.3.4.1/docs/python/html/_static/underscore.js +31 -0
  171. amps-python-client-5.3.4.1/docs/python/html/_static/up-pressed.png +0 -0
  172. amps-python-client-5.3.4.1/docs/python/html/_static/up.png +0 -0
  173. amps-python-client-5.3.4.1/docs/python/html/_static/websupport.js +808 -0
  174. amps-python-client-5.3.4.1/docs/python/html/chapters/advanced-topics.html +447 -0
  175. amps-python-client-5.3.4.1/docs/python/html/chapters/cpp-compiler-list.html +92 -0
  176. amps-python-client-5.3.4.1/docs/python/html/chapters/cpp-feature-table.html +156 -0
  177. amps-python-client-5.3.4.1/docs/python/html/chapters/creating-commands.html +2837 -0
  178. amps-python-client-5.3.4.1/docs/python/html/chapters/deltas.html +169 -0
  179. amps-python-client-5.3.4.1/docs/python/html/chapters/error-handling.html +746 -0
  180. amps-python-client-5.3.4.1/docs/python/html/chapters/exceptions.html +272 -0
  181. amps-python-client-5.3.4.1/docs/python/html/chapters/first-program.html +499 -0
  182. amps-python-client-5.3.4.1/docs/python/html/chapters/high-availability.html +1014 -0
  183. amps-python-client-5.3.4.1/docs/python/html/chapters/installing.html +264 -0
  184. amps-python-client-5.3.4.1/docs/python/html/chapters/introduction.html +245 -0
  185. amps-python-client-5.3.4.1/docs/python/html/chapters/moving-from-python-lite.html +118 -0
  186. amps-python-client-5.3.4.1/docs/python/html/chapters/performance-tips.html +499 -0
  187. amps-python-client-5.3.4.1/docs/python/html/chapters/queues.html +352 -0
  188. amps-python-client-5.3.4.1/docs/python/html/chapters/sow.html +381 -0
  189. amps-python-client-5.3.4.1/docs/python/html/chapters/subscriptions.html +535 -0
  190. amps-python-client-5.3.4.1/docs/python/html/chapters/utilities.html +302 -0
  191. amps-python-client-5.3.4.1/docs/python/html/genindex.html +351 -0
  192. amps-python-client-5.3.4.1/docs/python/html/index.html +380 -0
  193. amps-python-client-5.3.4.1/docs/python/html/objects.inv +0 -0
  194. amps-python-client-5.3.4.1/docs/python/html/search.html +107 -0
  195. amps-python-client-5.3.4.1/docs/python/html/searchindex.js +1 -0
  196. amps-python-client-5.3.4.1/docs/python-quickstart/doctrees/chapters/crankitup.doctree +0 -0
  197. amps-python-client-5.3.4.1/docs/python-quickstart/doctrees/chapters/equipment.doctree +0 -0
  198. amps-python-client-5.3.4.1/docs/python-quickstart/doctrees/environment.pickle +0 -0
  199. amps-python-client-5.3.4.1/docs/python-quickstart/doctrees/index.doctree +0 -0
  200. amps-python-client-5.3.4.1/docs/python-quickstart/html/.buildinfo +4 -0
  201. amps-python-client-5.3.4.1/docs/python-quickstart/html/_sources/chapters/crankitup.rst.txt +155 -0
  202. amps-python-client-5.3.4.1/docs/python-quickstart/html/_sources/chapters/equipment.rst.txt +19 -0
  203. amps-python-client-5.3.4.1/docs/python-quickstart/html/_sources/index.rst.txt +20 -0
  204. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/ajax-loader.gif +0 -0
  205. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/alabaster.css +699 -0
  206. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/basic.css +632 -0
  207. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/comment-bright.png +0 -0
  208. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/comment-close.png +0 -0
  209. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/comment.png +0 -0
  210. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/custom.css +192 -0
  211. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/custom.css.backup +161 -0
  212. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/doctools.js +287 -0
  213. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/down-pressed.png +0 -0
  214. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/down.png +0 -0
  215. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/file.png +0 -0
  216. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/flag_logo.png +0 -0
  217. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/flag_logo.svg +153 -0
  218. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/jquery-3.1.0.js +10074 -0
  219. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/jquery.js +4 -0
  220. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/minus.png +0 -0
  221. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/plus.png +0 -0
  222. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/pygments.css +74 -0
  223. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/searchtools.js +758 -0
  224. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/underscore-1.3.1.js +999 -0
  225. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/underscore.js +31 -0
  226. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/up-pressed.png +0 -0
  227. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/up.png +0 -0
  228. amps-python-client-5.3.4.1/docs/python-quickstart/html/_static/websupport.js +808 -0
  229. amps-python-client-5.3.4.1/docs/python-quickstart/html/chapters/crankitup.html +271 -0
  230. amps-python-client-5.3.4.1/docs/python-quickstart/html/chapters/equipment.html +105 -0
  231. amps-python-client-5.3.4.1/docs/python-quickstart/html/genindex.html +97 -0
  232. amps-python-client-5.3.4.1/docs/python-quickstart/html/index.html +382 -0
  233. amps-python-client-5.3.4.1/docs/python-quickstart/html/objects.inv +0 -0
  234. amps-python-client-5.3.4.1/docs/python-quickstart/html/search.html +107 -0
  235. amps-python-client-5.3.4.1/docs/python-quickstart/html/searchindex.js +1 -0
  236. amps-python-client-5.3.4.1/docs/resources/custom.css +9 -0
  237. amps-python-client-5.3.4.1/docs/resources/flag_logo.svg +153 -0
  238. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/acks.doctree +0 -0
  239. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/actions.doctree +0 -0
  240. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/amps-statistics.doctree +0 -0
  241. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/amps_expressions.doctree +0 -0
  242. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/amps_functions.doctree +0 -0
  243. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/auxiliary_modules.doctree +0 -0
  244. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/config-file-shortcuts.doctree +0 -0
  245. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/conflated_topics.doctree +0 -0
  246. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/constructing-fields.doctree +0 -0
  247. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/daemon.doctree +0 -0
  248. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/delta.doctree +0 -0
  249. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/distribution.doctree +0 -0
  250. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/enrichment.doctree +0 -0
  251. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/events.doctree +0 -0
  252. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/file_format_versions.doctree +0 -0
  253. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/glossary.doctree +0 -0
  254. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/ha.doctree +0 -0
  255. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/installing_and_starting.doctree +0 -0
  256. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/intro.doctree +0 -0
  257. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/logging.doctree +0 -0
  258. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/messageTypes.doctree +0 -0
  259. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/monitoring.doctree +0 -0
  260. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/oof.doctree +0 -0
  261. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/operation.doctree +0 -0
  262. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/pub_sub.doctree +0 -0
  263. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/queues.doctree +0 -0
  264. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/replication.doctree +0 -0
  265. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/securing.doctree +0 -0
  266. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/sow.doctree +0 -0
  267. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/sow_queries.doctree +0 -0
  268. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/spark.doctree +0 -0
  269. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/transports.doctree +0 -0
  270. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/troubleshooting.doctree +0 -0
  271. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/txlog.doctree +0 -0
  272. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/usecases.doctree +0 -0
  273. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/utilities.doctree +0 -0
  274. amps-python-client-5.3.4.1/docs/user-guide/doctrees/chapters/views.doctree +0 -0
  275. amps-python-client-5.3.4.1/docs/user-guide/doctrees/environment.pickle +0 -0
  276. amps-python-client-5.3.4.1/docs/user-guide/doctrees/index.doctree +0 -0
  277. amps-python-client-5.3.4.1/docs/user-guide/html/.buildinfo +4 -0
  278. amps-python-client-5.3.4.1/docs/user-guide/html/_images/AMPS-Queues-Intro.svg +1330 -0
  279. amps-python-client-5.3.4.1/docs/user-guide/html/_images/GeoRepl.png +0 -0
  280. amps-python-client-5.3.4.1/docs/user-guide/html/_images/HA_async_ack.png +0 -0
  281. amps-python-client-5.3.4.1/docs/user-guide/html/_images/HA_sync_ack.png +0 -0
  282. amps-python-client-5.3.4.1/docs/user-guide/html/_images/Hot-Hot-Replication.png +0 -0
  283. amps-python-client-5.3.4.1/docs/user-guide/html/_images/MessageOrdering.svg +235 -0
  284. amps-python-client-5.3.4.1/docs/user-guide/html/_images/OOF5.png +0 -0
  285. amps-python-client-5.3.4.1/docs/user-guide/html/_images/OOF6.png +0 -0
  286. amps-python-client-5.3.4.1/docs/user-guide/html/_images/OOF7.png +0 -0
  287. amps-python-client-5.3.4.1/docs/user-guide/html/_images/OOF8.png +0 -0
  288. amps-python-client-5.3.4.1/docs/user-guide/html/_images/PubSub1.svg +1 -0
  289. amps-python-client-5.3.4.1/docs/user-guide/html/_images/PubSub2.svg +1 -0
  290. amps-python-client-5.3.4.1/docs/user-guide/html/_images/SOWAndSubscribeAndReplace.svg +684 -0
  291. amps-python-client-5.3.4.1/docs/user-guide/html/_images/SOWQuery1.svg +402 -0
  292. amps-python-client-5.3.4.1/docs/user-guide/html/_images/SOWQuery2.svg +505 -0
  293. amps-python-client-5.3.4.1/docs/user-guide/html/_images/UseCaseFig1.svg +1 -0
  294. amps-python-client-5.3.4.1/docs/user-guide/html/_images/UseCaseFig2.svg +1 -0
  295. amps-python-client-5.3.4.1/docs/user-guide/html/_images/UseCaseFig3.svg +1 -0
  296. amps-python-client-5.3.4.1/docs/user-guide/html/_images/UseCaseFig4.svg +1 -0
  297. amps-python-client-5.3.4.1/docs/user-guide/html/_images/caution.png +0 -0
  298. amps-python-client-5.3.4.1/docs/user-guide/html/_images/caution.svg +25 -0
  299. amps-python-client-5.3.4.1/docs/user-guide/html/_images/chicago_group.png +0 -0
  300. amps-python-client-5.3.4.1/docs/user-guide/html/_images/delta_original_messages.png +0 -0
  301. amps-python-client-5.3.4.1/docs/user-guide/html/_images/delta_update_message.png +0 -0
  302. amps-python-client-5.3.4.1/docs/user-guide/html/_images/important.png +0 -0
  303. amps-python-client-5.3.4.1/docs/user-guide/html/_images/important.svg +25 -0
  304. amps-python-client-5.3.4.1/docs/user-guide/html/_images/inline_view_conflation.svg +1 -0
  305. amps-python-client-5.3.4.1/docs/user-guide/html/_images/paginated_subs_pub.png +0 -0
  306. amps-python-client-5.3.4.1/docs/user-guide/html/_images/paginated_subs_sub.png +0 -0
  307. amps-python-client-5.3.4.1/docs/user-guide/html/_images/queue_usage_overview.svg +627 -0
  308. amps-python-client-5.3.4.1/docs/user-guide/html/_images/replication_hub.png +0 -0
  309. amps-python-client-5.3.4.1/docs/user-guide/html/_images/replication_scenario_with_ha.png +0 -0
  310. amps-python-client-5.3.4.1/docs/user-guide/html/_images/sow_overview_1.svg +248 -0
  311. amps-python-client-5.3.4.1/docs/user-guide/html/_images/sow_overview_2.svg +183 -0
  312. amps-python-client-5.3.4.1/docs/user-guide/html/_images/sow_update_sequence.svg +1 -0
  313. amps-python-client-5.3.4.1/docs/user-guide/html/_images/tip.png +0 -0
  314. amps-python-client-5.3.4.1/docs/user-guide/html/_images/tip.svg +31 -0
  315. amps-python-client-5.3.4.1/docs/user-guide/html/_images/warning.png +0 -0
  316. amps-python-client-5.3.4.1/docs/user-guide/html/_images/warning.svg +23 -0
  317. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/acks.rst.txt +232 -0
  318. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/actions.rst.txt +111 -0
  319. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/amps-statistics.rst.txt +358 -0
  320. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/amps_expressions.rst.txt +83 -0
  321. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/amps_functions.rst.txt +11 -0
  322. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/auxiliary_modules.rst.txt +86 -0
  323. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/config-file-shortcuts.rst.txt +9 -0
  324. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/conflated_topics.rst.txt +111 -0
  325. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/constructing-fields.rst.txt +269 -0
  326. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/daemon.rst.txt +232 -0
  327. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/delta.rst.txt +556 -0
  328. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/distribution.rst.txt +186 -0
  329. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/enrichment.rst.txt +191 -0
  330. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/events.rst.txt +39 -0
  331. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/file_format_versions.rst.txt +203 -0
  332. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/glossary.rst.txt +101 -0
  333. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/ha.rst.txt +465 -0
  334. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/installing_and_starting.rst.txt +23 -0
  335. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/intro.rst.txt +116 -0
  336. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/logging.rst.txt +34 -0
  337. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/messageTypes.rst.txt +1398 -0
  338. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/monitoring.rst.txt +326 -0
  339. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/oof.rst.txt +312 -0
  340. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/operation.rst.txt +27 -0
  341. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/pub_sub.rst.txt +49 -0
  342. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/queues.rst.txt +1351 -0
  343. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/replication.rst.txt +1228 -0
  344. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/securing.rst.txt +657 -0
  345. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/sow.rst.txt +57 -0
  346. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/sow_queries.rst.txt +25 -0
  347. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/spark.rst.txt +824 -0
  348. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/transports.rst.txt +291 -0
  349. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/troubleshooting.rst.txt +517 -0
  350. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/txlog.rst.txt +62 -0
  351. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/usecases.rst.txt +21 -0
  352. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/utilities.rst.txt +62 -0
  353. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/views.rst.txt +175 -0
  354. amps-python-client-5.3.4.1/docs/user-guide/html/_sources/index.rst.txt +110 -0
  355. amps-python-client-5.3.4.1/docs/user-guide/html/_static/ajax-loader.gif +0 -0
  356. amps-python-client-5.3.4.1/docs/user-guide/html/_static/alabaster.css +695 -0
  357. amps-python-client-5.3.4.1/docs/user-guide/html/_static/basic.css +632 -0
  358. amps-python-client-5.3.4.1/docs/user-guide/html/_static/comment-bright.png +0 -0
  359. amps-python-client-5.3.4.1/docs/user-guide/html/_static/comment-close.png +0 -0
  360. amps-python-client-5.3.4.1/docs/user-guide/html/_static/comment.png +0 -0
  361. amps-python-client-5.3.4.1/docs/user-guide/html/_static/custom.css +192 -0
  362. amps-python-client-5.3.4.1/docs/user-guide/html/_static/custom.css.backup +161 -0
  363. amps-python-client-5.3.4.1/docs/user-guide/html/_static/doctools.js +287 -0
  364. amps-python-client-5.3.4.1/docs/user-guide/html/_static/down-pressed.png +0 -0
  365. amps-python-client-5.3.4.1/docs/user-guide/html/_static/down.png +0 -0
  366. amps-python-client-5.3.4.1/docs/user-guide/html/_static/file.png +0 -0
  367. amps-python-client-5.3.4.1/docs/user-guide/html/_static/flag_logo.png +0 -0
  368. amps-python-client-5.3.4.1/docs/user-guide/html/_static/flag_logo.svg +153 -0
  369. amps-python-client-5.3.4.1/docs/user-guide/html/_static/jquery-3.1.0.js +10074 -0
  370. amps-python-client-5.3.4.1/docs/user-guide/html/_static/jquery.js +4 -0
  371. amps-python-client-5.3.4.1/docs/user-guide/html/_static/minus.png +0 -0
  372. amps-python-client-5.3.4.1/docs/user-guide/html/_static/plus.png +0 -0
  373. amps-python-client-5.3.4.1/docs/user-guide/html/_static/pygments.css +74 -0
  374. amps-python-client-5.3.4.1/docs/user-guide/html/_static/searchtools.js +758 -0
  375. amps-python-client-5.3.4.1/docs/user-guide/html/_static/underscore-1.3.1.js +999 -0
  376. amps-python-client-5.3.4.1/docs/user-guide/html/_static/underscore.js +31 -0
  377. amps-python-client-5.3.4.1/docs/user-guide/html/_static/up-pressed.png +0 -0
  378. amps-python-client-5.3.4.1/docs/user-guide/html/_static/up.png +0 -0
  379. amps-python-client-5.3.4.1/docs/user-guide/html/_static/websupport.js +808 -0
  380. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/acks.html +289 -0
  381. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/actions.html +3782 -0
  382. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/amps-statistics.html +439 -0
  383. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/amps_expressions.html +1552 -0
  384. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/amps_functions.html +1626 -0
  385. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/auxiliary_modules.html +2548 -0
  386. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/config-file-shortcuts.html +508 -0
  387. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/conflated_topics.html +328 -0
  388. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/constructing-fields.html +447 -0
  389. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/daemon.html +295 -0
  390. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/delta.html +609 -0
  391. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/distribution.html +246 -0
  392. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/enrichment.html +264 -0
  393. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/events.html +449 -0
  394. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/file_format_versions.html +229 -0
  395. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/glossary.html +215 -0
  396. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/ha.html +978 -0
  397. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/installing_and_starting.html +357 -0
  398. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/intro.html +572 -0
  399. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/logging.html +972 -0
  400. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/messageTypes.html +1280 -0
  401. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/monitoring.html +718 -0
  402. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/oof.html +341 -0
  403. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/operation.html +1515 -0
  404. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/pub_sub.html +934 -0
  405. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/queues.html +1767 -0
  406. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/replication.html +1777 -0
  407. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/securing.html +697 -0
  408. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/sow.html +1038 -0
  409. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/sow_queries.html +621 -0
  410. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/spark.html +819 -0
  411. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/transports.html +352 -0
  412. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/troubleshooting.html +530 -0
  413. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/txlog.html +1013 -0
  414. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/usecases.html +288 -0
  415. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/utilities.html +133 -0
  416. amps-python-client-5.3.4.1/docs/user-guide/html/chapters/views.html +1120 -0
  417. amps-python-client-5.3.4.1/docs/user-guide/html/genindex.html +1261 -0
  418. amps-python-client-5.3.4.1/docs/user-guide/html/index.html +163 -0
  419. amps-python-client-5.3.4.1/docs/user-guide/html/objects.inv +0 -0
  420. amps-python-client-5.3.4.1/docs/user-guide/html/search.html +106 -0
  421. amps-python-client-5.3.4.1/docs/user-guide/html/searchindex.js +1 -0
  422. amps-python-client-5.3.4.1/include/ampspy_bookmarkstore.hpp +63 -0
  423. amps-python-client-5.3.4.1/include/ampspy_compat.h +63 -0
  424. amps-python-client-5.3.4.1/include/ampspy_defs.hpp +181 -0
  425. amps-python-client-5.3.4.1/include/ampspy_recoverypointadapter.hpp +52 -0
  426. amps-python-client-5.3.4.1/include/ampspy_shims.hpp +113 -0
  427. amps-python-client-5.3.4.1/include/ampspy_type_object.hpp +242 -0
  428. amps-python-client-5.3.4.1/include/ampspy_types.hpp +1139 -0
  429. amps-python-client-5.3.4.1/include/ampspyver.h +30 -0
  430. amps-python-client-5.3.4.1/index.html +66 -0
  431. amps-python-client-5.3.4.1/samples/AMPSConsolePublisher.py +59 -0
  432. amps-python-client-5.3.4.1/samples/AMPSConsoleSubscriber.py +63 -0
  433. amps-python-client-5.3.4.1/samples/AMPSFIXBuilderPublisher.py +71 -0
  434. amps-python-client-5.3.4.1/samples/AMPSFIXShredderSubscriber.py +69 -0
  435. amps-python-client-5.3.4.1/samples/AMPSNVFIXBuilderPublisher.py +71 -0
  436. amps-python-client-5.3.4.1/samples/AMPSNVFIXShredderSubscriber.py +67 -0
  437. amps-python-client-5.3.4.1/samples/AMPSPublishForReplay.py +81 -0
  438. amps-python-client-5.3.4.1/samples/AMPSQueueConsumer.py +69 -0
  439. amps-python-client-5.3.4.1/samples/AMPSQueuePublisher.py +59 -0
  440. amps-python-client-5.3.4.1/samples/AMPSSOWConsolePublisher.py +67 -0
  441. amps-python-client-5.3.4.1/samples/AMPSSOWConsoleSubscriber.py +77 -0
  442. amps-python-client-5.3.4.1/samples/AMPSSOWandSubscribeConsoleSubscriber.py +79 -0
  443. amps-python-client-5.3.4.1/samples/AMPSSOWandSubscribeWithOOF.py +108 -0
  444. amps-python-client-5.3.4.1/samples/AMPSSubscribeForReplay.py +128 -0
  445. amps-python-client-5.3.4.1/samples/AMPSUpdateForOOF.py +123 -0
  446. amps-python-client-5.3.4.1/samples/CompositeMessagePublisher.py +84 -0
  447. amps-python-client-5.3.4.1/samples/CompositeMessageSubscriber.py +87 -0
  448. amps-python-client-5.3.4.1/samples/RandomServerChooser.py +41 -0
  449. amps-python-client-5.3.4.1/samples/sample.xml +335 -0
  450. amps-python-client-5.3.4.1/setup.py +209 -0
  451. amps-python-client-5.3.4.1/setup_amps.py +94 -0
  452. amps-python-client-5.3.4.1/src/ampspy_shims.cpp +203 -0
  453. amps-python-client-5.3.4.1/src/ampspy_type_object.cpp +484 -0
  454. amps-python-client-5.3.4.1/src/authenticator.cpp +128 -0
  455. amps-python-client-5.3.4.1/src/bookmarkstore.cpp +238 -0
  456. amps-python-client-5.3.4.1/src/client.cpp +2430 -0
  457. amps-python-client-5.3.4.1/src/client_docs.h +956 -0
  458. amps-python-client-5.3.4.1/src/cmessagehandler.cpp +151 -0
  459. amps-python-client-5.3.4.1/src/command.cpp +164 -0
  460. amps-python-client-5.3.4.1/src/command_docs.h +194 -0
  461. amps-python-client-5.3.4.1/src/compositemessagebuilder.cpp +111 -0
  462. amps-python-client-5.3.4.1/src/compositemessageparser.cpp +146 -0
  463. amps-python-client-5.3.4.1/src/conflatingrecoverypointadapter.cpp +194 -0
  464. amps-python-client-5.3.4.1/src/cpp/include/amps/BlockPublishStore.hpp +2053 -0
  465. amps-python-client-5.3.4.1/src/cpp/include/amps/BlockStore.hpp +677 -0
  466. amps-python-client-5.3.4.1/src/cpp/include/amps/BookmarkStore.hpp +542 -0
  467. amps-python-client-5.3.4.1/src/cpp/include/amps/Buffer.hpp +214 -0
  468. amps-python-client-5.3.4.1/src/cpp/include/amps/CompositeMessageBuilder.hpp +174 -0
  469. amps-python-client-5.3.4.1/src/cpp/include/amps/CompositeMessageParser.hpp +151 -0
  470. amps-python-client-5.3.4.1/src/cpp/include/amps/DefaultServerChooser.hpp +162 -0
  471. amps-python-client-5.3.4.1/src/cpp/include/amps/Field.hpp +719 -0
  472. amps-python-client-5.3.4.1/src/cpp/include/amps/HAClient.hpp +370 -0
  473. amps-python-client-5.3.4.1/src/cpp/include/amps/HAClientImpl.hpp +460 -0
  474. amps-python-client-5.3.4.1/src/cpp/include/amps/HybridPublishStore.hpp +481 -0
  475. amps-python-client-5.3.4.1/src/cpp/include/amps/LoggedBookmarkStore.hpp +1255 -0
  476. amps-python-client-5.3.4.1/src/cpp/include/amps/MMapBookmarkStore.hpp +1283 -0
  477. amps-python-client-5.3.4.1/src/cpp/include/amps/MMapStoreBuffer.hpp +290 -0
  478. amps-python-client-5.3.4.1/src/cpp/include/amps/MemoryBookmarkStore.hpp +1622 -0
  479. amps-python-client-5.3.4.1/src/cpp/include/amps/MemoryPublishStore.hpp +66 -0
  480. amps-python-client-5.3.4.1/src/cpp/include/amps/MemoryStoreBuffer.hpp +244 -0
  481. amps-python-client-5.3.4.1/src/cpp/include/amps/MemorySubscriptionManager.hpp +850 -0
  482. amps-python-client-5.3.4.1/src/cpp/include/amps/Message.hpp +1819 -0
  483. amps-python-client-5.3.4.1/src/cpp/include/amps/MessageRouter.hpp +618 -0
  484. amps-python-client-5.3.4.1/src/cpp/include/amps/PublishStore.hpp +158 -0
  485. amps-python-client-5.3.4.1/src/cpp/include/amps/ReconnectDelayStrategy.hpp +106 -0
  486. amps-python-client-5.3.4.1/src/cpp/include/amps/ReconnectDelayStrategyImpl.hpp +317 -0
  487. amps-python-client-5.3.4.1/src/cpp/include/amps/RecoveryPoint.hpp +323 -0
  488. amps-python-client-5.3.4.1/src/cpp/include/amps/RecoveryPointAdapter.hpp +501 -0
  489. amps-python-client-5.3.4.1/src/cpp/include/amps/RingBookmarkStore.hpp +669 -0
  490. amps-python-client-5.3.4.1/src/cpp/include/amps/SOWRecoveryPointAdapter.hpp +490 -0
  491. amps-python-client-5.3.4.1/src/cpp/include/amps/ServerChooser.hpp +145 -0
  492. amps-python-client-5.3.4.1/src/cpp/include/amps/ServerChooserImpl.hpp +95 -0
  493. amps-python-client-5.3.4.1/src/cpp/include/amps/amps.h +775 -0
  494. amps-python-client-5.3.4.1/src/cpp/include/amps/amps_generated.h +46 -0
  495. amps-python-client-5.3.4.1/src/cpp/include/amps/amps_impl.h +204 -0
  496. amps-python-client-5.3.4.1/src/cpp/include/amps/amps_ssl.h +78 -0
  497. amps-python-client-5.3.4.1/src/cpp/include/amps/ampscrc.hpp +210 -0
  498. amps-python-client-5.3.4.1/src/cpp/include/amps/ampsplusplus.hpp +8817 -0
  499. amps-python-client-5.3.4.1/src/cpp/include/amps/ampsuri.h +84 -0
  500. amps-python-client-5.3.4.1/src/cpp/include/amps/ampsver.h +41 -0
  501. amps-python-client-5.3.4.1/src/cpp/include/amps/ampsver.h.in +41 -0
  502. amps-python-client-5.3.4.1/src/cpp/include/amps/constants.hpp +194 -0
  503. amps-python-client-5.3.4.1/src/cpp/include/amps/util.hpp +1692 -0
  504. amps-python-client-5.3.4.1/src/cpp/src/amps_protocol.c +688 -0
  505. amps-python-client-5.3.4.1/src/cpp/src/amps_protocol_generated.h +80 -0
  506. amps-python-client-5.3.4.1/src/cpp/src/amps_ssl.c +489 -0
  507. amps-python-client-5.3.4.1/src/cpp/src/atfork.c +446 -0
  508. amps-python-client-5.3.4.1/src/cpp/src/client.c +483 -0
  509. amps-python-client-5.3.4.1/src/cpp/src/makefile +92 -0
  510. amps-python-client-5.3.4.1/src/cpp/src/message.c +837 -0
  511. amps-python-client-5.3.4.1/src/cpp/src/message_generated.h +611 -0
  512. amps-python-client-5.3.4.1/src/cpp/src/tcp.c +1489 -0
  513. amps-python-client-5.3.4.1/src/cpp/src/tcps.c +1894 -0
  514. amps-python-client-5.3.4.1/src/cpp/src/transports.c +123 -0
  515. amps-python-client-5.3.4.1/src/cpp/src/unix.c +984 -0
  516. amps-python-client-5.3.4.1/src/cpp/src/uri.c +301 -0
  517. amps-python-client-5.3.4.1/src/exponentialdelaystrategy.cpp +137 -0
  518. amps-python-client-5.3.4.1/src/failedwritehandler.cpp +116 -0
  519. amps-python-client-5.3.4.1/src/fixbuilder.cpp +146 -0
  520. amps-python-client-5.3.4.1/src/fixeddelaystrategy.cpp +114 -0
  521. amps-python-client-5.3.4.1/src/fixshredder.cpp +105 -0
  522. amps-python-client-5.3.4.1/src/fixshredder_docs.h +38 -0
  523. amps-python-client-5.3.4.1/src/haclient.cpp +691 -0
  524. amps-python-client-5.3.4.1/src/haclient_docs.h +132 -0
  525. amps-python-client-5.3.4.1/src/hybridpublishstore.cpp +137 -0
  526. amps-python-client-5.3.4.1/src/hybridpublishstore_docs.h +31 -0
  527. amps-python-client-5.3.4.1/src/memorybookmarkstore.cpp +373 -0
  528. amps-python-client-5.3.4.1/src/memorybookmarkstore_docs.h +39 -0
  529. amps-python-client-5.3.4.1/src/memorypublishstore.cpp +160 -0
  530. amps-python-client-5.3.4.1/src/memorypublishstore_docs.h +32 -0
  531. amps-python-client-5.3.4.1/src/message.cpp +765 -0
  532. amps-python-client-5.3.4.1/src/message_docs.h +306 -0
  533. amps-python-client-5.3.4.1/src/messagestream.cpp +623 -0
  534. amps-python-client-5.3.4.1/src/messagestream_docs.h +45 -0
  535. amps-python-client-5.3.4.1/src/mmapbookmarkstore.cpp +422 -0
  536. amps-python-client-5.3.4.1/src/nvfixbuilder.cpp +160 -0
  537. amps-python-client-5.3.4.1/src/nvfixbuilder_docs.h +33 -0
  538. amps-python-client-5.3.4.1/src/nvfixshredder.cpp +99 -0
  539. amps-python-client-5.3.4.1/src/nvfixshredder_docs.h +39 -0
  540. amps-python-client-5.3.4.1/src/publishstore.cpp +183 -0
  541. amps-python-client-5.3.4.1/src/raw_wrapper.cpp +756 -0
  542. amps-python-client-5.3.4.1/src/reason.cpp +71 -0
  543. amps-python-client-5.3.4.1/src/recoverypoint.cpp +135 -0
  544. amps-python-client-5.3.4.1/src/recoverypointadapter.cpp +171 -0
  545. amps-python-client-5.3.4.1/src/ringbookmarkstore.cpp +360 -0
  546. amps-python-client-5.3.4.1/src/serverchooser.cpp +245 -0
  547. amps-python-client-5.3.4.1/src/serverchooser_docs.h +39 -0
  548. amps-python-client-5.3.4.1/src/sowrecoverypointadapter.cpp +248 -0
  549. amps-python-client-5.3.4.1/src/store.cpp +62 -0
  550. amps-python-client-5.3.4.1/src/versioninfo.cpp +175 -0
amps-python-client-5.3.4.1/docs/user-guide/html/chapters/auxiliary_modules.html ADDED
@@ -0,0 +1,2548 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+
4
+
5
+ <html xmlns="http://www.w3.org/1999/xhtml">
6
+ <head>
7
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8
+
9
+ <title>34. Auxiliary Modules &#8212; AMPS User Guide develop documentation</title>
10
+
11
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
12
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
13
+
14
+ <script type="text/javascript">
15
+ var DOCUMENTATION_OPTIONS = {
16
+ URL_ROOT: '../',
17
+ VERSION: 'develop',
18
+ COLLAPSE_INDEX: false,
19
+ FILE_SUFFIX: '.html',
20
+ HAS_SOURCE: true,
21
+ SOURCELINK_SUFFIX: '.txt'
22
+ };
23
+ </script>
24
+ <script type="text/javascript" src="../_static/jquery.js"></script>
25
+ <script type="text/javascript" src="../_static/underscore.js"></script>
26
+ <script type="text/javascript" src="../_static/doctools.js"></script>
27
+ <link rel="index" title="Index" href="../genindex.html" />
28
+ <link rel="search" title="Search" href="../search.html" />
29
+ <link rel="next" title="35. The AMPS Statistics Database" href="amps-statistics.html" />
30
+ <link rel="prev" title="33. Spark" href="spark.html" />
31
+
32
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
33
+
34
+
35
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
36
+
37
+ </head>
38
+ <body role="document">
39
+ <div class="document">
40
+
41
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
42
+ <div class="sphinxsidebarwrapper">
43
+ <p class="logo"><a href="../index.html">
44
+ <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
45
+ </a></p>
46
+ <h3><a href="../index.html">Table Of Contents</a></h3>
47
+ <ul>
48
+ <li><a class="reference internal" href="#">34. Auxiliary Modules</a><ul>
49
+ <li><a class="reference internal" href="#legacy-messaging-compatibility-functions">Legacy Messaging Compatibility Functions</a></li>
50
+ <li><a class="reference internal" href="#experimental-functions">Experimental Functions</a><ul>
51
+ <li><a class="reference internal" href="#preprocessing-enrichment">Preprocessing/Enrichment</a><ul>
52
+ <li><a class="reference internal" href="#limitations-and-usage">Limitations and Usage</a></li>
53
+ </ul>
54
+ </li>
55
+ <li><a class="reference internal" href="#loading-the-module">Loading the Module</a></li>
56
+ </ul>
57
+ </li>
58
+ <li><a class="reference internal" href="#key-generation-for-chained-messages">Key Generation for Chained Messages</a><ul>
59
+ <li><a class="reference internal" href="#chained-message-sample-case">Chained Message Sample Case</a></li>
60
+ <li><a class="reference internal" href="#configuring-the-chaining-key-generator">Configuring the Chaining Key Generator</a><ul>
61
+ <li><a class="reference internal" href="#example">Example</a></li>
62
+ </ul>
63
+ </li>
64
+ </ul>
65
+ </li>
66
+ <li><a class="reference internal" href="#authentication-and-entitlement-using-a-web-service">Authentication and Entitlement using a Web Service</a><ul>
67
+ <li><a class="reference internal" href="#when-to-use-the-web-service-module">When to Use the Web Service Module</a></li>
68
+ <li><a class="reference internal" href="#permissions-document-format">Permissions Document Format</a></li>
69
+ <li><a class="reference internal" href="#configuring-amps-to-use-web-service-authentication-and-entitlements">Configuring AMPS to use Web Service Authentication and Entitlements</a><ul>
70
+ <li><a class="reference internal" href="#using-https-for-authentication-and-entitlement-requests">Using HTTPS for Authentication and Entitlement Requests</a></li>
71
+ </ul>
72
+ </li>
73
+ <li><a class="reference internal" href="#permissions-management-and-request-flow">Permissions Management and Request Flow</a><ul>
74
+ <li><a class="reference internal" href="#authentication-step">Authentication Step</a></li>
75
+ <li><a class="reference internal" href="#entitlement-step">Entitlement Step</a></li>
76
+ <li><a class="reference internal" href="#entitlement-reset">Entitlement Reset</a></li>
77
+ <li><a class="reference internal" href="#entitlement-only-mode">Entitlement Only Mode</a></li>
78
+ <li><a class="reference internal" href="#entitlement-only-request-flow">Entitlement Only Request Flow</a></li>
79
+ </ul>
80
+ </li>
81
+ </ul>
82
+ </li>
83
+ <li><a class="reference internal" href="#authentication-with-the-amps-multimechanism-authentication-module">Authentication with the AMPS Multimechanism Authentication Module</a><ul>
84
+ <li><a class="reference internal" href="#when-to-use-the-multimechanism-authentication-module">When to Use the Multimechanism Authentication Module</a></li>
85
+ <li><a class="reference internal" href="#setting-authentication-mechanisms">Setting Authentication Mechanisms</a></li>
86
+ <li><a class="reference internal" href="#configuring-amps-to-use-the-multimechanism-authentication-module">Configuring AMPS to use the Multimechanism Authentication Module</a></li>
87
+ </ul>
88
+ </li>
89
+ <li><a class="reference internal" href="#entitlement-with-the-simple-access-module">Entitlement with the Simple Access Module</a><ul>
90
+ <li><a class="reference internal" href="#when-to-use-the-simple-access-module">When to Use the Simple Access Module</a></li>
91
+ <li><a class="reference internal" href="#configuring-amps-to-use-the-simple-access-module">Configuring AMPS to use the Simple Access Module</a></li>
92
+ </ul>
93
+ </li>
94
+ <li><a class="reference internal" href="#providing-replication-credentials-with-the-amps-multimechanism-authenticator-module">Providing Replication Credentials with the AMPS Multimechanism Authenticator Module</a><ul>
95
+ <li><a class="reference internal" href="#when-to-use-the-multimechanism-authenticator-module">When to Use the Multimechanism Authenticator Module</a></li>
96
+ <li><a class="reference internal" href="#id2">Setting Authentication Mechanisms</a></li>
97
+ <li><a class="reference internal" href="#configuring-amps-to-use-the-multimechanism-authenticator-module">Configuring AMPS to use the Multimechanism Authenticator Module</a></li>
98
+ </ul>
99
+ </li>
100
+ <li><a class="reference internal" href="#providing-replication-credentials-with-the-amps-exec-authenticator-module">Providing Replication Credentials with the AMPS Exec Authenticator Module</a><ul>
101
+ <li><a class="reference internal" href="#when-to-use-the-exec-authenticator-module">When to Use the Exec Authenticator Module</a></li>
102
+ <li><a class="reference internal" href="#configuring-amps-to-use-the-exec-authenticator-module">Configuring AMPS to use the Exec Authenticator Module</a></li>
103
+ </ul>
104
+ </li>
105
+ </ul>
106
+ </li>
107
+ </ul>
108
+ <div class="relations">
109
+ <h3>Related Topics</h3>
110
+ <ul>
111
+ <li><a href="../index.html">Documentation overview</a><ul>
112
+ <li>Previous: <a href="spark.html" title="previous chapter">33. Spark</a></li>
113
+ <li>Next: <a href="amps-statistics.html" title="next chapter">35. The AMPS Statistics Database</a></li>
114
+ </ul></li>
115
+ </ul>
116
+ </div>
117
+ <div id="searchbox" style="display: none" role="search">
118
+ <h3>Quick search</h3>
119
+ <form class="search" action="../search.html" method="get">
120
+ <div><input type="text" name="q" /></div>
121
+ <div><input type="submit" value="Go" /></div>
122
+ <input type="hidden" name="check_keywords" value="yes" />
123
+ <input type="hidden" name="area" value="default" />
124
+ </form>
125
+ </div>
126
+ <script type="text/javascript">$('#searchbox').show(0);</script>
127
+ </div>
128
+ </div>
129
+ <div class="documentwrapper">
130
+ <div class="bodywrapper">
131
+ <div class="body" role="main">
132
+
133
+ <div class="section" id="auxiliary-modules">
134
+ <span id="ug-appendix-auxilliary-modules"></span><span id="id1"></span><h1>34. Auxiliary Modules<a class="headerlink" href="#auxiliary-modules" title="Permalink to this headline">¶</a></h1>
135
+ <p>The AMPS distribution provides several modules that extend AMPS with
136
+ optional behavior. These modules are <em>not</em> loaded by default.</p>
137
+ <p>In this release, AMPS includes auxiliary modules that provide the
138
+ following functionality:</p>
139
+ <ul>
140
+ <li><p class="first"><strong>User-Defined Functions</strong></p>
141
+ <p>AMPS includes the <code class="docutils literal"><span class="pre">libamps_udf_legacy_compatibility</span></code> module that
142
+ provides date and time handling functions similar to those provided
143
+ by legacy messaging systems.</p>
144
+ <p>AMPS provides a <code class="docutils literal"><span class="pre">libamps_udf_experimental</span></code> module that contains
145
+ special purpose functions.</p>
146
+ </li>
147
+ <li><p class="first"><strong>SOW Key Generation</strong></p>
148
+ <p>AMPS includes the <code class="docutils literal"><span class="pre">libamps_id_chaining_generator</span></code> module that
149
+ provides chained SOW key generation.</p>
150
+ </li>
151
+ <li><p class="first"><strong>Authentication and Entitlement</strong></p>
152
+ <p>AMPS includes several modules to help you implement an authentication
153
+ and entitlement system.</p>
154
+ <ul class="simple">
155
+ <li>The <code class="docutils literal"><span class="pre">libamps_http_entitlement</span></code> module makes requests to an
156
+ external web service to validate authentication credentials and
157
+ retrieve the set of applicable entitlements. With this module,
158
+ you can provide both authentication and entitlement infrastructure.</li>
159
+ <li>The <code class="docutils literal"><span class="pre">libamps_multi_authentication</span></code> module supports multi-mechanism
160
+ authentication. In this release, the module supports both LDAP
161
+ and Kerberos. This module does not provide an entitlements
162
+ implementation.</li>
163
+ <li>The <code class="docutils literal"><span class="pre">libamps_simple_access_entitlement</span></code> module restricts access
164
+ to specific resources. This module is most often used to provide
165
+ limited access to the AMPS Admin console. This module does not
166
+ provide an authentication implementation, and does not consider
167
+ individual user entitlements &#8211; the restrictions applied by
168
+ this module apply to all users.</li>
169
+ </ul>
170
+ </li>
171
+ <li><p class="first"><strong>Authenticators</strong></p>
172
+ <ul class="simple">
173
+ <li>AMPS includes a module, <code class="docutils literal"><span class="pre">libamps_multi_authenticator</span></code>, to provide
174
+ credentials for outgoing replication connections. Notice that the default
175
+ authenticator module, which is automatically loaded, can also be
176
+ configured to provide credentials.</li>
177
+ <li>AMPS includes a module, <code class="docutils literal"><span class="pre">libamps_exec_authenticator</span></code>, that
178
+ executes an external application and provides the output of
179
+ that process as the credentials for an outgoing replication
180
+ connection.</li>
181
+ </ul>
182
+ </li>
183
+ </ul>
184
+ <p>The auxiliary modules are described in more detail in the following sections.</p>
185
+ <div class="section" id="legacy-messaging-compatibility-functions">
186
+ <span id="ug-legacy-messaging-compatibility"></span><h2>Legacy Messaging Compatibility Functions<a class="headerlink" href="#legacy-messaging-compatibility-functions" title="Permalink to this headline">¶</a></h2>
187
+ <p>The AMPS distribution includes a library of legacy messaging
188
+ compatibility functions. These functions are intended to ease migration
189
+ to AMPS from legacy messaging systems that provide similar functions.</p>
190
+ <p>In this release, the legacy messaging functions provide functions to
191
+ make it easy to work with date and time.</p>
192
+ <p>These functions are not loaded into AMPS by default. To enable them,
193
+ you must load the legacy messaging compatibility module by adding a
194
+ directive to the AMPS configuration file. Once the module is loaded,
195
+ the functions become available. No further configuration is required.</p>
196
+ <p>For example, adding the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code>
197
+ block of the AMPS configuration file loads the legacy messaging
198
+ compatibility functions.</p>
199
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
200
+ ...
201
+
202
+ <span class="nt">&lt;Modules&gt;</span>
203
+ ...
204
+
205
+ <span class="nt">&lt;Module&gt;</span>
206
+ <span class="nt">&lt;Name&gt;</span>compatibility-functions-module<span class="nt">&lt;/Name&gt;</span>
207
+ <span class="nt">&lt;Library&gt;</span>libamps_udf_legacy_compatibility.so<span class="nt">&lt;/Library&gt;</span>
208
+ <span class="nt">&lt;/Module&gt;</span>
209
+
210
+ <span class="nt">&lt;/Modules&gt;</span>
211
+
212
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
213
+ </pre></div>
214
+ </div>
215
+ <table border="1" class="docutils" id="id3">
216
+ <caption><span class="caption-text"><em>AMPS Legacy Messaging Compatibility Functions</em></span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
217
+ <colgroup>
218
+ <col width="33%" />
219
+ <col width="33%" />
220
+ <col width="33%" />
221
+ </colgroup>
222
+ <thead valign="bottom">
223
+ <tr class="row-odd"><th class="head">Function</th>
224
+ <th class="head">Parameters</th>
225
+ <th class="head">Description</th>
226
+ </tr>
227
+ </thead>
228
+ <tbody valign="top">
229
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">TIMEZONEOFFSET</span></code></td>
230
+ <td>&#160;</td>
231
+ <td>Returns a <code class="docutils literal"><span class="pre">long</span></code> that contains the current
232
+ timezone offset from UTC, represented in
233
+ seconds.</td>
234
+ </tr>
235
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">YEAR</span></code></td>
236
+ <td><em>timestamp</em></td>
237
+ <td>Returns the year for
238
+ the provided timestamp.
239
+ The year is calculated
240
+ in the UTC timezone.
241
+ For example, calling
242
+ <code class="docutils literal"><span class="pre">YEAR</span></code> on a timestamp
243
+ that represents January
244
+ 25, 2010 at 10:04 AM in
245
+ UTC returns <code class="docutils literal"><span class="pre">2010</span></code>.</td>
246
+ </tr>
247
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">MONTH</span></code></td>
248
+ <td><em>timestamp</em></td>
249
+ <td>Returns the month for
250
+ the provided timestamp.
251
+ The month is calculated
252
+ in the UTC timezone.
253
+ For example, calling
254
+ <code class="docutils literal"><span class="pre">MONTH</span></code> on a
255
+ timestamp that
256
+ represents January 25,
257
+ 2010 at 10:04 AM in UTC
258
+ returns <code class="docutils literal"><span class="pre">1</span></code>.</td>
259
+ </tr>
260
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">DAY</span></code></td>
261
+ <td><em>timestamp</em></td>
262
+ <td>Returns the day for the
263
+ provided timestamp. The
264
+ day is calculated in
265
+ the UTC timezone. For
266
+ example, calling
267
+ <code class="docutils literal"><span class="pre">DAY</span></code> on a timestamp
268
+ that represents January
269
+ 25, 2010 at 10:04 AM in
270
+ UTC returns <code class="docutils literal"><span class="pre">25</span></code>.</td>
271
+ </tr>
272
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">DATE_UTC</span></code></td>
273
+ <td><em>timestamp</em></td>
274
+ <td>Returns a timestamp for
275
+ the beginning of the
276
+ provided day (00:00:00)
277
+ in UTC. The timestamp is
278
+ represented in seconds.</td>
279
+ </tr>
280
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">DATE</span></code></td>
281
+ <td><em>timestamp</em></td>
282
+ <td>Returns the UNIX timestamp for
283
+ the beginning of the
284
+ provided day (00:00:00)
285
+ in the local timezone. The timestamp is
286
+ represented in seconds.</td>
287
+ </tr>
288
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">TODAY_UTC</span></code></td>
289
+ <td>&#160;</td>
290
+ <td>Returns the UNIX timestamp for
291
+ the beginning of the
292
+ current day (00:00:00)
293
+ in UTC &#8211; that is, the local timestamp that
294
+ corresponds to the UTC time for the start of
295
+ the current day. The timestamp is
296
+ represented in seconds.</td>
297
+ </tr>
298
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">TODAY</span></code></td>
299
+ <td>&#160;</td>
300
+ <td>Returns the UNIX timestamp for
301
+ the beginning of the
302
+ current day (00:00:00)
303
+ in the local timezone. The timestamp is
304
+ represented in seconds.</td>
305
+ </tr>
306
+ </tbody>
307
+ </table>
308
+ </div>
309
+ <div class="section" id="experimental-functions">
310
+ <span id="ug-udf-experimental"></span><h2>Experimental Functions<a class="headerlink" href="#experimental-functions" title="Permalink to this headline">¶</a></h2>
311
+ <p>This module contains User-Defined Functions (UDF) that are a part of the
312
+ AMPS distribution, but which serve specialized use cases and are
313
+ not currently intended for use outside of those scenarios. The
314
+ current implementations of these UDFs are considered to be
315
+ experimental and are only supported for use in the intended context
316
+ &#8211; a general-purpose version of these features might behave somewhat
317
+ differently.</p>
318
+ <p>In this release, the experimental UDF module contains one function
319
+ for use in preprocessing or enrichment.</p>
320
+ <div class="section" id="preprocessing-enrichment">
321
+ <h3>Preprocessing/Enrichment<a class="headerlink" href="#preprocessing-enrichment" title="Permalink to this headline">¶</a></h3>
322
+ <p>The <code class="docutils literal"><span class="pre">VALUE_LOOKUP</span></code> function can be used to look up a value in another topic
323
+ during preprocessing or enrichment of a SOW topic.</p>
324
+ <p>To use the function, you must first load the experimental UDF module and
325
+ register the lookups that will be used by the module.</p>
326
+ <p>A lookup is declared using the Lookup option to the module. This option
327
+ uses a semicolon-delimited list of parameters to define the lookup. All
328
+ parameters are required.</p>
329
+ <table border="1" class="docutils" id="id4">
330
+ <caption><span class="caption-text"><em>Lookup option parameters</em></span><a class="headerlink" href="#id4" title="Permalink to this table">¶</a></caption>
331
+ <colgroup>
332
+ <col width="50%" />
333
+ <col width="50%" />
334
+ </colgroup>
335
+ <thead valign="bottom">
336
+ <tr class="row-odd"><th class="head"><strong>Option</strong></th>
337
+ <th class="head"><strong>Definition</strong></th>
338
+ </tr>
339
+ </thead>
340
+ <tbody valign="top">
341
+ <tr class="row-even"><td>Name</td>
342
+ <td>The name to use for the lookup.</td>
343
+ </tr>
344
+ <tr class="row-odd"><td>Parameter Count</td>
345
+ <td>The number of fields to use for
346
+ the lookup.</td>
347
+ </tr>
348
+ <tr class="row-even"><td>Message Type</td>
349
+ <td>The message type of the topic to
350
+ use for lookup.</td>
351
+ </tr>
352
+ <tr class="row-odd"><td>Topic Name</td>
353
+ <td>The name of the topic to use for
354
+ lookup.</td>
355
+ </tr>
356
+ <tr class="row-even"><td>Return Field</td>
357
+ <td>The field to return from the
358
+ located message.</td>
359
+ </tr>
360
+ <tr class="row-odd"><td>Lookup Fields</td>
361
+ <td>The fields to use to look up the
362
+ message.</td>
363
+ </tr>
364
+ </tbody>
365
+ </table>
366
+ <p>For example, to create a lookup named <code class="docutils literal"><span class="pre">return-value-by-id</span></code>,
367
+ that takes a single parameter and uses that to match the
368
+ <code class="docutils literal"><span class="pre">/id</span></code> field in the <code class="docutils literal"><span class="pre">data</span></code> topic of <code class="docutils literal"><span class="pre">json</span></code> type, returning
369
+ the <code class="docutils literal"><span class="pre">/value</span></code> field of the matched record, you would provide
370
+ this option when loading the module:</p>
371
+ <div class="code xml highlight-default"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Lookup</span><span class="o">&gt;</span><span class="k">return</span><span class="o">-</span><span class="n">value</span><span class="o">-</span><span class="n">by</span><span class="o">-</span><span class="nb">id</span><span class="p">;</span><span class="mi">1</span><span class="p">;</span><span class="n">json</span><span class="p">;</span><span class="n">data</span><span class="p">;</span><span class="o">/</span><span class="n">value</span><span class="p">;</span><span class="o">/</span><span class="nb">id</span><span class="o">&lt;/</span><span class="n">Lookup</span><span class="o">&gt;</span>
372
+ </pre></div>
373
+ </div>
374
+ <p>Likewise, to create a lookup named <code class="docutils literal"><span class="pre">getNotes</span></code> that uses a
375
+ combination of <code class="docutils literal"><span class="pre">/customerId</span></code> and <code class="docutils literal"><span class="pre">/orderId</span></code> to return the
376
+ <code class="docutils literal"><span class="pre">/notes</span></code> field of a matching record from the orders topic of
377
+ <code class="docutils literal"><span class="pre">nvfix</span></code> type, you would provide this option when loading the
378
+ module:</p>
379
+ <div class="code xml highlight-default"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Lookup</span><span class="o">&gt;</span><span class="n">getNotes</span><span class="p">;</span><span class="mi">2</span><span class="p">;</span><span class="n">nvfix</span><span class="p">;</span><span class="n">orders</span><span class="p">;</span><span class="o">/</span><span class="n">notes</span><span class="p">;</span><span class="o">/</span><span class="n">customerId</span><span class="p">;</span><span class="o">/</span><span class="n">orderId</span><span class="o">&lt;/</span><span class="n">Lookup</span><span class="o">&gt;</span>
380
+ </pre></div>
381
+ </div>
382
+ <p>To use the UDF, provide the name of the lookup and the values to lookup:</p>
383
+ <div class="code sql highlight-default"><div class="highlight"><pre><span></span><span class="n">VALUE_LOOKUP</span><span class="p">(</span><span class="s2">&quot;return-value-by-id&quot;</span><span class="p">,</span> <span class="o">/</span><span class="n">thisId</span><span class="p">)</span>
384
+ </pre></div>
385
+ </div>
386
+ <p>The above function call will take the <code class="docutils literal"><span class="pre">/thisId</span></code> field from the current
387
+ message, use that to find a matching <code class="docutils literal"><span class="pre">/id</span></code> value in the data topic (of
388
+ <code class="docutils literal"><span class="pre">json</span></code> type), and then return the <code class="docutils literal"><span class="pre">/value</span></code> field from a matching record.</p>
389
+ <p>The <code class="docutils literal"><span class="pre">VALUE_LOOKUP</span></code> function uses an exact match for the fields specified.</p>
390
+ <table border="1" class="docutils" id="id5">
391
+ <caption><span class="caption-text"><em>VALUE_LOOKUP function</em></span><a class="headerlink" href="#id5" title="Permalink to this table">¶</a></caption>
392
+ <colgroup>
393
+ <col width="33%" />
394
+ <col width="33%" />
395
+ <col width="33%" />
396
+ </colgroup>
397
+ <thead valign="bottom">
398
+ <tr class="row-odd"><th class="head">Function</th>
399
+ <th class="head">Parameters</th>
400
+ <th class="head">Description</th>
401
+ </tr>
402
+ </thead>
403
+ <tbody valign="top">
404
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">VALUE_LOOKUP</span></code></td>
405
+ <td><p class="first"><em>name of lookup</em></p>
406
+ <p><em>one or more values
407
+ for lookup</em></p>
408
+ <p class="last">The number of values
409
+ provided must match
410
+ the definition for
411
+ the lookup name.</p>
412
+ </td>
413
+ <td><p class="first">Returns a value from the
414
+ referenced topic as a string.</p>
415
+ <p class="last">If multiple records match the
416
+ lookup, returns one of those
417
+ records. If no records match the
418
+ lookup, returns <code class="docutils literal"><span class="pre">NULL</span></code>.</p>
419
+ </td>
420
+ </tr>
421
+ </tbody>
422
+ </table>
423
+ <p>To use this function, the module must be loaded and one or more lookup
424
+ functions must be declared when the module is loaded, as described
425
+ in this section. This function is not loaded by default.</p>
426
+ <div class="section" id="limitations-and-usage">
427
+ <h4>Limitations and Usage<a class="headerlink" href="#limitations-and-usage" title="Permalink to this headline">¶</a></h4>
428
+ <p>This UDF has the following limitations:</p>
429
+ <ul class="simple">
430
+ <li>60East makes no particular performance guarantees for this UDF, but
431
+ recommends that the topics used for lookup be relatively small topics
432
+ with infrequently updated data.</li>
433
+ <li>The UDF caches lookup results for performance. This means that the UDF
434
+ will increase the memory footprint of the AMPS instance (typically by
435
+ the size of the lookup values + the size of the return values + 32
436
+ bytes per record indexed in the target topic + a small amount of
437
+ overhead per defined lookup).</li>
438
+ <li>The lookup returns the value retrieved as an AMPS string. As with
439
+ all AMPS values, if the value of the string can be coerced to a number,
440
+ it can be used as a numeric value.</li>
441
+ <li>If a lookup results in multiple matches, the UDF will return values
442
+ for one of the matching records, but does not guarantee which
443
+ result will be returned.</li>
444
+ <li>The lookup function should only be used in preprocessing and enrichment
445
+ in cases where it is not possible to use a view instead. The function
446
+ cannot be used in view definitions, since it cannot guarantee that data
447
+ is available during view recovery. The function cannot be used for a
448
+ SOW topic with <code class="docutils literal"><span class="pre">transient</span></code> durability and a recovery point other than
449
+ <code class="docutils literal"><span class="pre">now</span></code>, since the function cannot guarantee that data is available during
450
+ SOW recovery.</li>
451
+ <li>Values provided are cached for performance and the cache is updated
452
+ asynchronously. This means that a publish to the source topic
453
+ immediately followed by a call to the UDF may or may not produce
454
+ the newly published value.</li>
455
+ <li>AMPS considers the lookup function non-deterministic,
456
+ since the value returned depends on the state of a message stored
457
+ in a SOW topic, rather than the message being currently evaluated.</li>
458
+ </ul>
459
+ </div>
460
+ </div>
461
+ <div class="section" id="loading-the-module">
462
+ <h3>Loading the Module<a class="headerlink" href="#loading-the-module" title="Permalink to this headline">¶</a></h3>
463
+ <p>The experimental functions module is shipped in the AMPS <code class="docutils literal"><span class="pre">lib</span></code> directory,
464
+ and is named <code class="docutils literal"><span class="pre">libamps_udf_experimental.so</span></code>. To use the module, you load it
465
+ as shown below, providing any options necessary for the functions
466
+ contained in the module.</p>
467
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
468
+ <span class="nt">&lt;Module&gt;</span>
469
+ <span class="nt">&lt;Name&gt;</span>experimental-udf<span class="nt">&lt;/Name&gt;</span>
470
+ <span class="nt">&lt;Library&gt;</span>libamps_udf_experimental.so<span class="nt">&lt;/Library&gt;</span>
471
+ <span class="nt">&lt;Options&gt;</span>
472
+ <span class="nt">&lt;Lookup&gt;</span>value-by-id;1;json;source-sow;/value;/id<span class="nt">&lt;/Lookup&gt;</span>
473
+ <span class="nt">&lt;Lookup&gt;</span>customer-id-by-order-id;1;nvfix;orders;/id;/customerId<span class="nt">&lt;/Lookup&gt;</span>
474
+ <span class="nt">&lt;/Options&gt;</span>
475
+ <span class="nt">&lt;/Module&gt;</span>
476
+ <span class="nt">&lt;/Modules&gt;</span>
477
+ </pre></div>
478
+ </div>
479
+ </div>
480
+ </div>
481
+ <div class="section" id="key-generation-for-chained-messages">
482
+ <h2>Key Generation for Chained Messages<a class="headerlink" href="#key-generation-for-chained-messages" title="Permalink to this headline">¶</a></h2>
483
+ <p>The AMPS distribution includes a module that can generate a SOW key for
484
+ a set of chained messages.</p>
485
+ <p>Message chains are most frequently used in FIX order processing systems
486
+ to track a set of updates to an original order from a set of systems
487
+ that use unique local identifiers for the order. As messages arrive,
488
+ AMPS must update the record for the original order, regardless of
489
+ whether the identifier on the current message is the original order, or
490
+ is an order chained to the original order.</p>
491
+ <p>A message chain allows an application to treat any update to an
492
+ identifier in the chain as an update to the original message in the
493
+ chain. The <code class="docutils literal"><span class="pre">libamps_id_chaining_key_generator</span></code> module supports this by
494
+ generating the same SOW key for any message in the chain. To use this
495
+ module, messages must have a field that identifies the current message
496
+ and a field that identifies the previous message in the message chain,
497
+ if one exists.</p>
498
+ <div class="section" id="chained-message-sample-case">
499
+ <h3>Chained Message Sample Case<a class="headerlink" href="#chained-message-sample-case" title="Permalink to this headline">¶</a></h3>
500
+ <p>Consider a message processing scheme that uses two fields to identify
501
+ related messages. Each message contains a <code class="docutils literal"><span class="pre">DocumentNumber</span></code> field
502
+ that indicates the current document. If the message updates or extends
503
+ an existing document, the message contains a <code class="docutils literal"><span class="pre">ParentDocument</span></code> that,
504
+ when present, refers to the <code class="docutils literal"><span class="pre">DocumentNumber</span></code> of the document that the
505
+ message updates or extends.</p>
506
+ <p>With the default SOW key generator, each of the following messages would
507
+ be a distinct message in the SOW topic:</p>
508
+ <div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="nx">delta_publish</span><span class="o">:</span> <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Status&quot;</span><span class="o">:</span><span class="s2">&quot;Started&quot;</span><span class="p">}</span>
509
+ <span class="nx">delta_publish</span><span class="o">:</span> <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">2</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Order&quot;</span><span class="o">:</span><span class="s2">&quot;Antivenom&quot;</span><span class="p">}</span>
510
+ <span class="nx">delta_publish</span><span class="o">:</span> <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">3</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">2</span><span class="p">,</span> <span class="s2">&quot;Order&quot;</span><span class="o">:</span><span class="s2">&quot;Sandwich&quot;</span><span class="p">}</span>
511
+ <span class="nx">delta_publish</span><span class="o">:</span> <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">4</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Status&quot;</span><span class="o">:</span><span class="s2">&quot;Pending&quot;</span><span class="p">}</span>
512
+ </pre></div>
513
+ </div>
514
+ <p>With the default SOW key generator, at the end of the publishing
515
+ process, the SOW contains four distinct records:</p>
516
+ <div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Status&quot;</span><span class="o">:</span><span class="s2">&quot;Started&quot;</span><span class="p">}</span>
517
+ <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">2</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Order&quot;</span><span class="o">:</span><span class="s2">&quot;Antivenom&quot;</span><span class="p">}</span>
518
+ <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">3</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">2</span><span class="p">,</span> <span class="s2">&quot;Order&quot;</span><span class="o">:</span><span class="s2">&quot;Sandwich&quot;</span><span class="p">}</span>
519
+ <span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">4</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">1</span><span class="p">,</span> <span class="s2">&quot;Status&quot;</span><span class="o">:</span><span class="s2">&quot;Pending&quot;</span><span class="p">}</span>
520
+ </pre></div>
521
+ </div>
522
+ <p>However, with the chaining key generator, AMPS is able to combine these
523
+ messages into a single chain and produces the following single record:</p>
524
+ <div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;DocumentNumber&quot;</span><span class="o">:</span><span class="mf">4</span><span class="p">,</span> <span class="s2">&quot;ParentDocument&quot;</span><span class="o">:</span><span class="mf">1</span> <span class="p">,</span> <span class="s2">&quot;Order&quot;</span><span class="o">:</span><span class="s2">&quot;Sandwich&quot;</span><span class="p">,</span> <span class="s2">&quot;Status&quot;</span><span class="o">:</span><span class="s2">&quot;Pending&quot;</span><span class="p">}</span>
525
+ </pre></div>
526
+ </div>
527
+ <p>The sequence of events for producing this message is as follows:</p>
528
+ <ul class="simple">
529
+ <li>When the first message arrives with a <code class="docutils literal"><span class="pre">/DocumentNumber</span></code> of <code class="docutils literal"><span class="pre">1</span></code>,
530
+ the module begins a new chain (since there is no <code class="docutils literal"><span class="pre">/ParentDocument</span></code>
531
+ present).</li>
532
+ <li>When the second message arrives, the module knows that it is an
533
+ update to the same message since the message contains a
534
+ <code class="docutils literal"><span class="pre">/ParentDocument</span></code> value. In this case, because the value is <code class="docutils literal"><span class="pre">1</span></code>,
535
+ the update is to the first message received. The module also adds a
536
+ <code class="docutils literal"><span class="pre">/DocumentNumber</span></code> of <code class="docutils literal"><span class="pre">2</span></code> to the chain, so that subsequent
537
+ messages that refer to a <code class="docutils literal"><span class="pre">/ParentDocument</span></code> of <code class="docutils literal"><span class="pre">2</span></code> are a part of
538
+ the chain and update the same message.</li>
539
+ <li>The same process occurs for the third message: the module looks up
540
+ the message that should be updated when the <code class="docutils literal"><span class="pre">/ParentDocument</span></code> is
541
+ <code class="docutils literal"><span class="pre">2</span></code>, and traces the chain back to the original underlying message.
542
+ The module adds a <code class="docutils literal"><span class="pre">/DocumentNumber</span></code> of <code class="docutils literal"><span class="pre">3</span></code> to the chain, so that
543
+ updates with a <code class="docutils literal"><span class="pre">/ParentDocument</span></code> of <code class="docutils literal"><span class="pre">3</span></code> will update the same
544
+ message.</li>
545
+ <li>When the last message arrives, the module knows that a
546
+ <code class="docutils literal"><span class="pre">/ParentDocument</span></code> of <code class="docutils literal"><span class="pre">1</span></code> is still an update to the same message,
547
+ since this is the original value. The module adds the value <code class="docutils literal"><span class="pre">4</span></code> to
548
+ the chain.</li>
549
+ </ul>
550
+ <p>In each case, rather than simply using the fields in the message
551
+ directly, the module creates a chain of linked identifiers: each
552
+ identifier in the chain produces the same SOW key as the first
553
+ identifier in the chain, so each update in the chain updates the same
554
+ message.</p>
555
+ <p>It is an error for a publisher to publish a message that resolves to two
556
+ different message chains. If the module receives such a message, the
557
+ module will not generate a SOW key, and the message is not processed by
558
+ AMPS.</p>
559
+ </div>
560
+ <div class="section" id="configuring-the-chaining-key-generator">
561
+ <h3>Configuring the Chaining Key Generator<a class="headerlink" href="#configuring-the-chaining-key-generator" title="Permalink to this headline">¶</a></h3>
562
+ <p>To load the module in AMPS, add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code>
563
+ block of the AMPS configuration file:</p>
564
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
565
+ ...
566
+
567
+ <span class="nt">&lt;Modules&gt;</span>
568
+ ...
569
+
570
+ <span class="nt">&lt;Module&gt;</span>
571
+ <span class="nt">&lt;Name&gt;</span>key-chaining<span class="nt">&lt;/Name&gt;</span>
572
+ <span class="nt">&lt;Library&gt;</span>libamps_id_chaining_key_generator.so<span class="nt">&lt;/Library&gt;</span>
573
+ <span class="nt">&lt;/Module&gt;</span>
574
+
575
+ <span class="nt">&lt;/Modules&gt;</span>
576
+
577
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
578
+ </pre></div>
579
+ </div>
580
+ <p>You then use the module as the <code class="docutils literal"><span class="pre">KeyGenerator</span></code> for each topic in the
581
+ SOW that will use chaining key generation.</p>
582
+ <p>The module accepts the following options:</p>
583
+ <table border="1" class="docutils" id="id6">
584
+ <caption><span class="caption-text"><em>Parameters for chaining key generator</em></span><a class="headerlink" href="#id6" title="Permalink to this table">¶</a></caption>
585
+ <colgroup>
586
+ <col width="50%" />
587
+ <col width="50%" />
588
+ </colgroup>
589
+ <thead valign="bottom">
590
+ <tr class="row-odd"><th class="head">Parameter</th>
591
+ <th class="head">Description</th>
592
+ </tr>
593
+ </thead>
594
+ <tbody valign="top">
595
+ <tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">Key</span>
596
+ </pre></div>
597
+ </div>
598
+ </td>
599
+ <td><p class="first">A field to use in chaining. AMPS supports any number
600
+ of <code class="docutils literal"><span class="pre">Key</span></code> fields.</p>
601
+ <p>The first <code class="docutils literal"><span class="pre">Key</span></code> field specified in the configuration
602
+ is the <em>primary field</em> to use in chaining. When the
603
+ primary field is present on a message, and the value
604
+ of the field <em>is not</em> in an existing chain of values,
605
+ the module creates a new chain.</p>
606
+ <p>When the message contains the <em>primary field</em>
607
+ and there is no previous entry for the value of that
608
+ field, this message is the head of the chain and is
609
+ used to generate the SOW key.</p>
610
+ <p><code class="docutils literal"><span class="pre">Key</span></code> parameters specified after the first <code class="docutils literal"><span class="pre">Key</span></code>
611
+ are <em>secondary fields</em>.</p>
612
+ <p>When a secondary field is present on the message, the
613
+ module generates a SOW key for this message as
614
+ though the message contained a primary field
615
+ with this value. In addition, the module stores the
616
+ value of the primary field in the current, if any,
617
+ message as equivalent to this value, enabling
618
+ subsequent messages to be chained to this message.</p>
619
+ <p>There is no default for this parameter. The
620
+ parameter requires an AMPS field identifier, such as
621
+ <code class="docutils literal"><span class="pre">/11</span></code> or <code class="docutils literal"><span class="pre">/Order/ClOrdID</span></code>.</p>
622
+ <p class="last">The module requires a primary field and at least one
623
+ secondary field to be defined.</p>
624
+ </td>
625
+ </tr>
626
+ <tr class="row-odd"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">FileName</span>
627
+ </pre></div>
628
+ </div>
629
+ </td>
630
+ <td><p class="first">Sets the name of the file that the module uses to
631
+ store chaining data.</p>
632
+ <p class="last">This module persists existing chains between restarts
633
+ of the AMPS server. If a file with the given name
634
+ exists when AMPS starts, the module reads chaining
635
+ data from the file. Otherwise, the module creates a
636
+ new file.</p>
637
+ </td>
638
+ </tr>
639
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Primary</span></code></td>
640
+ <td><p class="first">A synonym for <code class="docutils literal"><span class="pre">Key</span></code> that explicitly specifies
641
+ that this field is the primary field.</p>
642
+ <p class="last">When this configuration element is present, AMPS uses
643
+ the field specified in this element as the <em>primary
644
+ field</em> and considers any field specified in a <code class="docutils literal"><span class="pre">Key</span></code>
645
+ element to be a secondary field.</p>
646
+ </td>
647
+ </tr>
648
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">Secondary</span></code></td>
649
+ <td>A synonym for <code class="docutils literal"><span class="pre">Key</span></code> that explicitly specifies that
650
+ this field is a secondary field.</td>
651
+ </tr>
652
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Validation</span></code></td>
653
+ <td><p class="first">Specifies whether the module validates that incoming
654
+ messages are properly chained. When set to <code class="docutils literal"><span class="pre">true</span></code>
655
+ or <code class="docutils literal"><span class="pre">1</span></code>, the module records extra data to attempt
656
+ to detect errors in the sequencing of the chain. The
657
+ module will consider it an error when it detects
658
+ that two or more distinct chains share identifiers
659
+ and would have been combined into a single chain had
660
+ messages arrived in a different order. In some
661
+ systems, this indicates an error in message
662
+ processing.</p>
663
+ <p class="last">Default: This option defaults to <code class="docutils literal"><span class="pre">false</span></code>.</p>
664
+ </td>
665
+ </tr>
666
+ </tbody>
667
+ </table>
668
+ <div class="section" id="example">
669
+ <h4>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h4>
670
+ <p>The example configuration file below shows one way to use the chaining
671
+ key generator module.</p>
672
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
673
+ ...
674
+
675
+ <span class="nt">&lt;Module&gt;</span>
676
+ <span class="nt">&lt;Name&gt;</span>key-chaining<span class="nt">&lt;/Name&gt;</span>
677
+ <span class="nt">&lt;Library&gt;</span>libamps_id_chaining_key_generator.so<span class="nt">&lt;/Library&gt;</span>
678
+ <span class="nt">&lt;/Module&gt;</span>
679
+ <span class="nt">&lt;/Modules&gt;</span>
680
+
681
+ <span class="nt">&lt;SOW&gt;</span>
682
+ ...
683
+
684
+ <span class="nt">&lt;Topic&gt;</span>
685
+ <span class="nt">&lt;Name&gt;</span>Orders<span class="nt">&lt;/Name&gt;</span>
686
+ <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
687
+ <span class="nt">&lt;KeyGenerator&gt;</span>
688
+ <span class="nt">&lt;Module&gt;</span>key-chaining<span class="nt">&lt;/Module&gt;</span>
689
+ <span class="nt">&lt;Options&gt;</span>
690
+ <span class="nt">&lt;Primary&gt;</span>/DocumentNumber<span class="nt">&lt;/Primary&gt;</span>
691
+ <span class="nt">&lt;Key&gt;</span>/ParentDocument<span class="nt">&lt;/Key&gt;</span>
692
+ <span class="nt">&lt;Key&gt;</span>/RelatedDocument<span class="nt">&lt;/Key&gt;</span>
693
+ <span class="nt">&lt;FileName&gt;</span>./sow/Orders.chain<span class="nt">&lt;/FileName&gt;</span>
694
+ <span class="nt">&lt;/Options&gt;</span>
695
+ <span class="nt">&lt;/KeyGenerator&gt;</span>
696
+ <span class="nt">&lt;FileName&gt;</span>./sow/%n.sow<span class="nt">&lt;/FileName&gt;</span>
697
+ <span class="nt">&lt;/Topic&gt;</span>
698
+
699
+ <span class="nt">&lt;Topic&gt;</span>
700
+ <span class="nt">&lt;Name&gt;</span>ExternalOrders<span class="nt">&lt;/Name&gt;</span>
701
+ <span class="nt">&lt;MessageType&gt;</span>fix<span class="nt">&lt;/MessageType&gt;</span>
702
+ <span class="nt">&lt;KeyGenerator&gt;</span>
703
+ <span class="nt">&lt;Module&gt;</span>key-chaining<span class="nt">&lt;/Module&gt;</span>
704
+ <span class="nt">&lt;Options&gt;</span>
705
+ <span class="c">&lt;!-- /11 is the primary field --&gt;</span>
706
+ <span class="nt">&lt;Key&gt;</span>/11<span class="nt">&lt;/Key&gt;</span>
707
+ <span class="nt">&lt;Key&gt;</span>/41<span class="nt">&lt;/Key&gt;</span>
708
+ <span class="nt">&lt;FileName&gt;</span>./sow/ExternalOrders.chain<span class="nt">&lt;/FileName&gt;</span>
709
+ <span class="nt">&lt;/Options&gt;</span>
710
+ <span class="nt">&lt;/KeyGenerator&gt;</span>
711
+ <span class="nt">&lt;FileName&gt;</span>./sow/%n.sow<span class="nt">&lt;/FileName&gt;</span>
712
+ <span class="nt">&lt;/Topic&gt;</span>
713
+ <span class="nt">&lt;/SOW&gt;</span>
714
+ </pre></div>
715
+ </div>
716
+ <p>Notice that once the module is loaded, it can be used for any message
717
+ type, and can accept different configuration values for each topic in
718
+ the SOW that uses the generator.</p>
719
+ </div>
720
+ </div>
721
+ </div>
722
+ <div class="section" id="authentication-and-entitlement-using-a-web-service">
723
+ <span id="ug-auth-module"></span><h2>Authentication and Entitlement using a Web Service<a class="headerlink" href="#authentication-and-entitlement-using-a-web-service" title="Permalink to this headline">¶</a></h2>
724
+ <p>The AMPS distribution includes a module that provides authentication and
725
+ entitlement via an external Web Service. For some installations, this
726
+ module provides a convenient way to integrate with an existing
727
+ authentication and entitlement infrastructure without creating an
728
+ entitlement plugin.</p>
729
+ <p>In this release, the HTTP authentication module is provided with AMPS,
730
+ but is not loaded by default. This module is an optional extension to
731
+ the AMPS product, and while it is included with the AMPS distribution,
732
+ the module must be explicitly loaded, enabled, and configured.</p>
733
+ <p>When using this module, AMPS requests permissions documents from an
734
+ external service using <code class="docutils literal"><span class="pre">http</span></code> or <code class="docutils literal"><span class="pre">https</span></code>. The request to retrieve
735
+ the permissions document includes the credentials provided with the
736
+ client logon. If the request succeeds, the module considers the user to
737
+ have successfully authenticated to AMPS. If the request to retrieve the
738
+ permissions document fails, the module considers the user to have failed
739
+ authentication. When authentication succeeds, the contents of the
740
+ document returned specify the permissions that the module grants to the
741
+ user.</p>
742
+ <p>The web service module expects that the web service endpoint will follow RESTful
743
+ (HTTP) semantics. For example, the module uses standard HTTP headers for
744
+ authentication and expects that if the credentials provided are not valid,
745
+ the endpoint will return an HTTP 403 status code (or equivalent).</p>
746
+ <div class="section" id="when-to-use-the-web-service-module">
747
+ <h3>When to Use the Web Service Module<a class="headerlink" href="#when-to-use-the-web-service-module" title="Permalink to this headline">¶</a></h3>
748
+ <p>The AMPS Web Service Authentication and Entitlement module can be a good
749
+ option when:</p>
750
+ <ul class="simple">
751
+ <li>The site does not have an existing authentication and entitlements
752
+ infrastructure for AMPS.</li>
753
+ <li>It is more feasible to develop and test a standalone web service than
754
+ to develop a server plugin for AMPS.</li>
755
+ <li>Applications need to integrate with an existing authentication and
756
+ entitlement system that offers limited Linux or C/C++ support.</li>
757
+ <li>An application that will use another authentication scheme in
758
+ production needs an easy way to test changes to entitlements and
759
+ entitlement scenarios that are difficult to replicate in the
760
+ production system.</li>
761
+ </ul>
762
+ </div>
763
+ <div class="section" id="permissions-document-format">
764
+ <h3>Permissions Document Format<a class="headerlink" href="#permissions-document-format" title="Permalink to this headline">¶</a></h3>
765
+ <p>This section describes the format of the permissions documents used by
766
+ the Web Service Authentication and Entitlement module.</p>
767
+ <p>All documents are in JSON format, and consist of a set of permissions.
768
+ The document <em>is not required</em> to contain the user name: this is
769
+ intentional, and allows systems to easily provide identical permissions for
770
+ all users in a group without having to create unique documents.</p>
771
+ <p>The entitlement document expresses each permission as a field of a JSON
772
+ document. The following is an example of a permissions document:</p>
773
+ <div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
774
+ <span class="s2">&quot;logon&quot;</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
775
+ <span class="s2">&quot;replication-logon&quot;</span> <span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
776
+ <span class="s2">&quot;topic&quot;</span><span class="o">:</span> <span class="p">[</span>
777
+ <span class="p">{</span> <span class="s2">&quot;topic&quot;</span><span class="o">:</span> <span class="s2">&quot;test&quot;</span><span class="p">,</span>
778
+ <span class="s2">&quot;read&quot;</span><span class="o">:</span> <span class="s2">&quot;/priority = 1&quot;</span><span class="p">,</span>
779
+ <span class="s2">&quot;write&quot;</span><span class="o">:</span> <span class="kc">false</span> <span class="p">},</span>
780
+ <span class="p">{</span> <span class="s2">&quot;topic&quot;</span><span class="o">:</span> <span class="s2">&quot;.*&quot;</span><span class="p">,</span>
781
+ <span class="s2">&quot;read&quot;</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
782
+ <span class="s2">&quot;write&quot;</span><span class="o">:</span> <span class="kc">true</span> <span class="p">}</span>
783
+ <span class="p">],</span>
784
+ <span class="s2">&quot;admin&quot;</span><span class="o">:</span> <span class="p">[</span>
785
+ <span class="p">{</span> <span class="s2">&quot;topic&quot;</span><span class="o">:</span> <span class="s2">&quot;^/amps/instance/.*&quot;</span><span class="p">,</span>
786
+ <span class="s2">&quot;read&quot;</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
787
+ <span class="s2">&quot;write&quot;</span><span class="o">:</span> <span class="kc">false</span> <span class="p">},</span>
788
+ <span class="p">{</span> <span class="s2">&quot;topic&quot;</span><span class="o">:</span> <span class="s2">&quot;.*&quot;</span><span class="p">,</span>
789
+ <span class="s2">&quot;read&quot;</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
790
+ <span class="s2">&quot;write&quot;</span><span class="o">:</span> <span class="kc">false</span> <span class="p">}</span>
791
+ <span class="p">]</span>
792
+ <span class="p">}</span>
793
+ </pre></div>
794
+ </div>
795
+ <p>The Web Authentication Module processes the entitlements in document
796
+ order. Going through the document in order, this set of entitlements
797
+ specifies the following permissions:</p>
798
+ <ul class="simple">
799
+ <li>This user has permission to log on to AMPS, as set by the logon
800
+ field.</li>
801
+ <li>This user does not have permission to make a replication connection
802
+ to AMPS. A replication connection that uses these credentials will be
803
+ refused.</li>
804
+ <li>This user has read permissions to the topic <code class="docutils literal"><span class="pre">test</span></code> for messages
805
+ that match the filter <code class="docutils literal"><span class="pre">/priority</span> <span class="pre">=</span> <span class="pre">1</span></code>. This user does not have
806
+ write permissions to the topic.</li>
807
+ <li>The user has read and write permissions to every other topic in the
808
+ instance without content restrictions.</li>
809
+ <li>The user has read permissions to the administrative interface for
810
+ information under the <code class="docutils literal"><span class="pre">/amps/instance</span></code> path.</li>
811
+ <li>The user has no other permissions to the administrative interface.</li>
812
+ </ul>
813
+ <p>The Web Service Authentication and Entitlement Module also allows
814
+ fine-grained control of the topics that a given user is allowed to
815
+ publish to via replication with the <code class="docutils literal"><span class="pre">replicated-topics</span></code> configuration
816
+ element. The following permissions document shows sample permissions for
817
+ a replication connection:</p>
818
+ <div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
819
+ <span class="s2">&quot;replication-logon&quot;</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
820
+ <span class="s2">&quot;logon&quot;</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
821
+ <span class="s2">&quot;replicated-topics&quot;</span><span class="o">:</span><span class="p">[</span><span class="s2">&quot;^/orders/NYC/.*&quot;</span><span class="p">,</span>
822
+ <span class="s2">&quot;/events/P1&quot;</span><span class="p">]</span>
823
+ <span class="p">}</span>
824
+ </pre></div>
825
+ </div>
826
+ <p>This document specifies that the user can only log on to AMPS via
827
+ replication connections. The user has permission to replicate messages
828
+ to the topic <code class="docutils literal"><span class="pre">/events/P1</span></code> (using an exact match) and topics that begin
829
+ with <code class="docutils literal"><span class="pre">/orders/NYC</span></code>, as specified by the regular expression
830
+ <code class="docutils literal"><span class="pre">^/orders/NYC/.*</span></code>. The user has no other permissions. In particular,
831
+ the user cannot log on from an AMPS client, and could not publish to or
832
+ subscribe to any topics even if <code class="docutils literal"><span class="pre">logon</span></code> was changed to <code class="docutils literal"><span class="pre">true</span></code>
833
+ without an explicit <code class="docutils literal"><span class="pre">topic</span></code> permission.</p>
834
+ <p>The structure of the permissions document is as follows:</p>
835
+ <table border="1" class="colwidths-given docutils" id="id7">
836
+ <caption><span class="caption-text"><em>Client Transport Permissions</em></span><a class="headerlink" href="#id7" title="Permalink to this table">¶</a></caption>
837
+ <colgroup>
838
+ <col width="30%" />
839
+ <col width="70%" />
840
+ </colgroup>
841
+ <thead valign="bottom">
842
+ <tr class="row-odd"><th class="head">Field</th>
843
+ <th class="head">Value</th>
844
+ </tr>
845
+ </thead>
846
+ <tbody valign="top">
847
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">logon</span></code></td>
848
+ <td><p class="first">Specifies permission for an application
849
+ to log on to AMPS.</p>
850
+ <p class="last">When this field is present, the value of
851
+ the field must be a boolean <code class="docutils literal"><span class="pre">true</span></code> or
852
+ <code class="docutils literal"><span class="pre">false</span></code>.</p>
853
+ </td>
854
+ </tr>
855
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">topic</span></code></td>
856
+ <td><p class="first">Controls access to topics within AMPS.</p>
857
+ <p>When this field is present, the value of
858
+ the field must be a <em>permission list</em>, as
859
+ described below.</p>
860
+ <p class="last">If this field is not present, the user
861
+ cannot publish to or subscribe to any
862
+ topics.</p>
863
+ </td>
864
+ </tr>
865
+ </tbody>
866
+ </table>
867
+ <table border="1" class="colwidths-given docutils" id="id8">
868
+ <caption><span class="caption-text"><em>Admin Interface Permissions</em></span><a class="headerlink" href="#id8" title="Permalink to this table">¶</a></caption>
869
+ <colgroup>
870
+ <col width="30%" />
871
+ <col width="70%" />
872
+ </colgroup>
873
+ <thead valign="bottom">
874
+ <tr class="row-odd"><th class="head">Field</th>
875
+ <th class="head">Value</th>
876
+ </tr>
877
+ </thead>
878
+ <tbody valign="top">
879
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">admin</span></code></td>
880
+ <td><p class="first">Controls access to the administrative
881
+ interface.</p>
882
+ <p>When this field is present,
883
+ the value of the field must be a
884
+ <em>permission list</em>, as described below.</p>
885
+ <p>If this field is not present, the user
886
+ has no access to the administrative
887
+ interface.</p>
888
+ <p class="last">Notice that, because the Admin console
889
+ uses HTTP, there is no equivalent of the
890
+ <cite>logon</cite> or <cite>replication-logon</cite> permission
891
+ for the Admin transport.</p>
892
+ </td>
893
+ </tr>
894
+ </tbody>
895
+ </table>
896
+ <table border="1" class="colwidths-given docutils" id="id9">
897
+ <caption><span class="caption-text"><em>Replication Transport Permissions</em></span><a class="headerlink" href="#id9" title="Permalink to this table">¶</a></caption>
898
+ <colgroup>
899
+ <col width="30%" />
900
+ <col width="70%" />
901
+ </colgroup>
902
+ <thead valign="bottom">
903
+ <tr class="row-odd"><th class="head">Field</th>
904
+ <th class="head">Value</th>
905
+ </tr>
906
+ </thead>
907
+ <tbody valign="top">
908
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">replication-logon</span></code></td>
909
+ <td><p class="first">Controls permission for a replication
910
+ connection to log on to AMPS.</p>
911
+ <p class="last">When this field is present, the value of
912
+ this field must be a boolean <code class="docutils literal"><span class="pre">true</span></code> or
913
+ <code class="docutils literal"><span class="pre">false</span></code>.</p>
914
+ </td>
915
+ </tr>
916
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">replicated-topics</span></code></td>
917
+ <td><p class="first">An array containing the topics that this
918
+ user can replicate to.</p>
919
+ <p>When this field is present, the value of
920
+ the field must be an array of strings that
921
+ specify topic names or regular expressions.
922
+ For example, the following entry allows
923
+ this user to replicate ONLY to topics that
924
+ begin with <code class="docutils literal"><span class="pre">/orders/NYC</span></code></p>
925
+ <div class="code highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;replicated-topics&quot;</span><span class="p">:[</span><span class="s2">&quot;^/orders/NYC/.*&quot;</span><span class="p">]</span>
926
+ </pre></div>
927
+ </div>
928
+ <p class="last">If this field is not present in the
929
+ permissions document, the user cannot
930
+ replicate to any topics.</p>
931
+ </td>
932
+ </tr>
933
+ </tbody>
934
+ </table>
935
+ <table border="1" class="colwidths-given docutils" id="id10">
936
+ <caption><span class="caption-text"><em>Connection Properties</em></span><a class="headerlink" href="#id10" title="Permalink to this table">¶</a></caption>
937
+ <colgroup>
938
+ <col width="30%" />
939
+ <col width="70%" />
940
+ </colgroup>
941
+ <thead valign="bottom">
942
+ <tr class="row-odd"><th class="head">Field</th>
943
+ <th class="head">Value</th>
944
+ </tr>
945
+ </thead>
946
+ <tbody valign="top">
947
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">user_name</span></code></td>
948
+ <td><p class="first">Specifies that the module should set
949
+ the authenticated user name of the
950
+ connection to the provided value.</p>
951
+ <p>This option is ignored when the module
952
+ is in <code class="docutils literal"><span class="pre">EntitlementsOnly</span></code> mode.</p>
953
+ <p class="last">If this field is not present in the
954
+ returned permissions document, the
955
+ authenticated user name is set to the
956
+ value provided with the <code class="docutils literal"><span class="pre">logon</span></code>
957
+ request from the client.</p>
958
+ </td>
959
+ </tr>
960
+ </tbody>
961
+ </table>
962
+ <p>Permissions lists within this document are arrays of entries. Each entry
963
+ in the array is a JSON object with the following format:</p>
964
+ <table border="1" class="docutils" id="id11">
965
+ <caption><span class="caption-text"><em>Permission list format</em></span><a class="headerlink" href="#id11" title="Permalink to this table">¶</a></caption>
966
+ <colgroup>
967
+ <col width="50%" />
968
+ <col width="50%" />
969
+ </colgroup>
970
+ <thead valign="bottom">
971
+ <tr class="row-odd"><th class="head">Field</th>
972
+ <th class="head">Value</th>
973
+ </tr>
974
+ </thead>
975
+ <tbody valign="top">
976
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">topic</span></code></td>
977
+ <td><p class="first">The name of the topic this permission
978
+ definition applies to.</p>
979
+ <p>This name can be either a literal value,
980
+ or a regular expression to use to match
981
+ topic names.</p>
982
+ <p class="last">A name is interpreted as a regular
983
+ expression if it contains any characters
984
+ used in regular expression matching (for
985
+ example; <code class="docutils literal"><span class="pre">^</span></code>, <code class="docutils literal"><span class="pre">$</span></code>, <code class="docutils literal"><span class="pre">*</span></code>, <code class="docutils literal"><span class="pre">.</span></code> and
986
+ so on). Regular expression matching
987
+ provides full support for PCRE regular
988
+ expressions.</p>
989
+ </td>
990
+ </tr>
991
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">read</span></code></td>
992
+ <td><p class="first">Defines the read permission for the
993
+ topic.</p>
994
+ <p>The value of this field can be either
995
+ <code class="docutils literal"><span class="pre">true</span></code>, <code class="docutils literal"><span class="pre">false</span></code> or an AMPS filter</p>
996
+ <p class="last">When the value is <code class="docutils literal"><span class="pre">true</span></code>, the module
997
+ grants read permission to the topic with
998
+ no restrictions. When the value is
999
+ <code class="docutils literal"><span class="pre">false</span></code>, the module denies read
1000
+ permission. When the value is a filter,
1001
+ the module grants read permission to the
1002
+ topic only for those messages that match
1003
+ the filter.</p>
1004
+ </td>
1005
+ </tr>
1006
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">write</span></code></td>
1007
+ <td><p class="first">Defines the write permission for the
1008
+ topic.</p>
1009
+ <p>The value of this field can be either
1010
+ <code class="docutils literal"><span class="pre">true</span></code>, <code class="docutils literal"><span class="pre">false</span></code> or an AMPS filter</p>
1011
+ <p class="last">When the value is <code class="docutils literal"><span class="pre">true</span></code>, the module
1012
+ grants write permission to the topic with
1013
+ no restrictions. When the value is
1014
+ <code class="docutils literal"><span class="pre">false</span></code>, the module denies write
1015
+ permission. When the value is a filter,
1016
+ the module grants write permission to
1017
+ the topic only for those messages that
1018
+ match the filter.</p>
1019
+ </td>
1020
+ </tr>
1021
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">select</span></code></td>
1022
+ <td><p class="first">Defines the entitlement select list for
1023
+ this topic.</p>
1024
+ <p>When this value is present,
1025
+ the module applies the select list
1026
+ provided to the topic entitlement.</p>
1027
+ <p class="last">Notice that this element should include
1028
+ <em>only</em> the select list specifier and not
1029
+ the enclosing brackets for the select
1030
+ list. For example, a valid <code class="docutils literal"><span class="pre">select</span></code>
1031
+ element might be:</p>
1032
+ </td>
1033
+ </tr>
1034
+ </tbody>
1035
+ </table>
1036
+ </div>
1037
+ <div class="section" id="configuring-amps-to-use-web-service-authentication-and-entitlements">
1038
+ <h3>Configuring AMPS to use Web Service Authentication and Entitlements<a class="headerlink" href="#configuring-amps-to-use-web-service-authentication-and-entitlements" title="Permalink to this headline">¶</a></h3>
1039
+ <p>The web service authentication and entitlement module is included in the
1040
+ AMPS distribution, but is not loaded by default. To load the module in
1041
+ AMPS, add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code> block
1042
+ of the AMPS configuration file:</p>
1043
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
1044
+ ...
1045
+
1046
+ <span class="nt">&lt;Module&gt;</span>
1047
+ <span class="nt">&lt;Name&gt;</span>web-entitlements<span class="nt">&lt;/Name&gt;</span>
1048
+ <span class="nt">&lt;Library&gt;</span>libamps_http_entitlement.so<span class="nt">&lt;/Library&gt;</span>
1049
+
1050
+ <span class="c">&lt;!-- You may specify options here, or where the module is used.--&gt;</span>
1051
+ <span class="nt">&lt;/Module&gt;</span>
1052
+
1053
+ ...
1054
+ <span class="nt">&lt;/Modules&gt;</span>
1055
+ </pre></div>
1056
+ </div>
1057
+ <p>Options for the module may be set when the module is loaded, when the
1058
+ module is used for <code class="docutils literal"><span class="pre">Authentication</span></code> or <code class="docutils literal"><span class="pre">Entitlement</span></code>, or in both
1059
+ places. Options set when the module is loaded are inherited as the
1060
+ default values for all uses of the module in the instance. Options
1061
+ specified in an <code class="docutils literal"><span class="pre">Authentication</span></code> or <code class="docutils literal"><span class="pre">Entitlement</span></code> block override
1062
+ options set when the module is loaded.</p>
1063
+ <p>For <code class="docutils literal"><span class="pre">Authentication</span></code>, the module supports the following options:</p>
1064
+ <table border="1" class="docutils" id="id12">
1065
+ <caption><span class="caption-text"><em>Options in Authentication directive</em></span><a class="headerlink" href="#id12" title="Permalink to this table">¶</a></caption>
1066
+ <colgroup>
1067
+ <col width="50%" />
1068
+ <col width="50%" />
1069
+ </colgroup>
1070
+ <thead valign="bottom">
1071
+ <tr class="row-odd"><th class="head">Option</th>
1072
+ <th class="head">Description</th>
1073
+ </tr>
1074
+ </thead>
1075
+ <tbody valign="top">
1076
+ <tr class="row-even"><td><div class="req first last docutils container">
1077
+ ResourceURI</div>
1078
+ </td>
1079
+ <td><p class="first">The URI to request when a user logs
1080
+ into AMPS using this module. This
1081
+ option is required.</p>
1082
+ <p>For this option, AMPS substitutes
1083
+ the placeholder <code class="docutils literal"><span class="pre">{{USER_NAME}}</span></code>
1084
+ with the name of the user being
1085
+ authenticated. For example, here are
1086
+ two possible values for the
1087
+ <code class="docutils literal"><span class="pre">ResourceURI</span></code>:</p>
1088
+ <div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">cred</span><span class="o">-</span><span class="n">server</span><span class="p">:</span><span class="mi">8080</span><span class="o">/</span><span class="p">{{</span><span class="n">USER_NAME</span><span class="p">}}</span><span class="o">.</span><span class="n">json</span>
1089
+ </pre></div>
1090
+ </div>
1091
+ <div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">cred</span><span class="o">-</span><span class="n">server</span><span class="p">:</span><span class="mi">8080</span><span class="o">/</span><span class="n">admin</span><span class="o">/</span><span class="n">group_policy</span><span class="o">.</span><span class="n">json</span>
1092
+ </pre></div>
1093
+ </div>
1094
+ <p>In the first case, AMPS requests a
1095
+ document with the current user name
1096
+ of the user logging on substituted
1097
+ for the <code class="docutils literal"><span class="pre">{{USER_NAME}}</span></code> component
1098
+ of the URI. In the second case, the
1099
+ document is requested with the
1100
+ credentials of the user connecting,
1101
+ but AMPS requests the same document
1102
+ for each user.</p>
1103
+ <p class="last">There is no default for this
1104
+ parameter.</p>
1105
+ </td>
1106
+ </tr>
1107
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">CredentialStore</span></code></td>
1108
+ <td><p class="first">Identifier for the entitlement store
1109
+ where the retrieved permission sets
1110
+ will be stored. When used for
1111
+ authentication, this is the name of
1112
+ the entitlement cache that the
1113
+ module stores parsed information
1114
+ into until AMPS requests the
1115
+ information.</p>
1116
+ <p>In most cases, there is no need to
1117
+ set this parameter. When multiple
1118
+ transports use different
1119
+ <code class="docutils literal"><span class="pre">ResourceURI</span></code> values, but those
1120
+ transports are expected to maintain
1121
+ the same information, specifying a
1122
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> value can speed
1123
+ the logon process and reduce the
1124
+ number of copies of the parsed
1125
+ permissions document in memory.
1126
+ Likewise, if a module must ensure
1127
+ that permission sets are kept
1128
+ separate (so that, for example, an
1129
+ internal user named <code class="docutils literal"><span class="pre">'johndoe'</span></code>
1130
+ and a web user named <code class="docutils literal"><span class="pre">'johndoe'</span></code>
1131
+ have separate credentials),
1132
+ explicitly setting a
1133
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> value can make
1134
+ it easier to verify that the
1135
+ permission sets are completely
1136
+ separate.</p>
1137
+ <p class="last">Default: The literal value of the
1138
+ <code class="docutils literal"><span class="pre">ResourceURI</span></code> parameter.</p>
1139
+ </td>
1140
+ </tr>
1141
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">ConnectionTimeout</span></code></td>
1142
+ <td><p class="first">The maximum amount of time to wait
1143
+ for a connection to the web server
1144
+ for each request, in milliseconds.
1145
+ If a connection is not made within
1146
+ the specified time, the module stops
1147
+ the connection attempt and the
1148
+ request fails.</p>
1149
+ <p class="last">Default: <code class="docutils literal"><span class="pre">2000</span></code></p>
1150
+ </td>
1151
+ </tr>
1152
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">RequestTimeout</span></code></td>
1153
+ <td><p class="first">The maximum amount of time to wait
1154
+ for the web server to return a
1155
+ permissions document on each
1156
+ request, in milliseconds. If the
1157
+ server does not return a permissions
1158
+ document within the specified time,
1159
+ the module closes the connection and
1160
+ the request fails.</p>
1161
+ <div class="admonition tip">
1162
+ <p class="first admonition-title">Tip</p>
1163
+ <p class="last">Increasing this timeout above the default
1164
+ value may produce potential stuck thread
1165
+ warnings if the web service is slow to
1166
+ respond.</p>
1167
+ </div>
1168
+ <p class="last">Default: <code class="docutils literal"><span class="pre">5000</span></code></p>
1169
+ </td>
1170
+ </tr>
1171
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">RetryCount</span></code></td>
1172
+ <td><p class="first">Sets the number of times to retry
1173
+ the request if retrieving the
1174
+ authentication document fails for
1175
+ any reason.</p>
1176
+ <p class="last">Default: <code class="docutils literal"><span class="pre">0</span></code> (only try once)</p>
1177
+ </td>
1178
+ </tr>
1179
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">HTTPHeader</span></code></td>
1180
+ <td><p class="first">Sets a header to add to the HTTP
1181
+ request. The configuration can
1182
+ specify any number of <code class="docutils literal"><span class="pre">HTTPHeader</span></code>
1183
+ elements, and the module will
1184
+ provide each of the specified
1185
+ headers with the authentication
1186
+ request.</p>
1187
+ <p>There is no default for this option.
1188
+ If no <code class="docutils literal"><span class="pre">HTTPHeader</span></code> option is
1189
+ included, the module provides a
1190
+ standard set of headers.</p>
1191
+ <p>This option supports variable
1192
+ replacement during an authentication
1193
+ request, as described in the following table.</p>
1194
+ <p class="last">This option supports expansion of the
1195
+ <code class="docutils literal"><span class="pre">AMPS_USER_NAME</span></code>
1196
+ (and the <code class="docutils literal"><span class="pre">USER_NAME</span></code>
1197
+ backward compatibility form) when the module
1198
+ is in <code class="docutils literal"><span class="pre">EntitlementsOnly</span></code> mode.</p>
1199
+ </td>
1200
+ </tr>
1201
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">EntitlementTimeout</span></code></td>
1202
+ <td><p class="first">Optionally, sets the amount of time to consider
1203
+ an entitlements document to be valid. After this
1204
+ timeout period, if an authentication request
1205
+ returns a different entitlements document, the
1206
+ module will reset permissions for all connections
1207
+ currently connected with the username being
1208
+ authenticated (which will disconnect those
1209
+ connections and clear the entitlement cache).</p>
1210
+ <p>When this option is not provided, the module
1211
+ retains permissions until all connections with the
1212
+ current user name are disconnected, then removes
1213
+ cached permissions in the module and clears the
1214
+ AMPS entitlement cache.</p>
1215
+ <p>This option is not supported in
1216
+ <code class="docutils literal"><span class="pre">EntitlementsOnly</span></code> mode.</p>
1217
+ <p>This option accepts a number of milliseconds or
1218
+ an AMPS interval.</p>
1219
+ <p class="last">The granularity for the <code class="docutils literal"><span class="pre">EntitlementTimeout</span></code> is
1220
+ a second. Fractions of a second, or values less
1221
+ than one second, may be rounded or truncated.</p>
1222
+ </td>
1223
+ </tr>
1224
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">ReuseConnections</span></code></td>
1225
+ <td><p class="first">Optionally, sets the module to reuse connections
1226
+ to the entitlement service when possible. By
1227
+ default, the module creates a new connection for
1228
+ each entitlement request.</p>
1229
+ <p>When set to <code class="docutils literal"><span class="pre">enabled</span></code>, the module will reuse
1230
+ HTTP connections when possible.</p>
1231
+ <p>This option is only supported within the
1232
+ <code class="docutils literal"><span class="pre">Modules</span></code> definition, and is set for all
1233
+ uses of the module within the configuration.
1234
+ The option will be ignored if it is set within
1235
+ the <code class="docutils literal"><span class="pre">Authentication</span></code> or <code class="docutils literal"><span class="pre">Entitlement</span></code>
1236
+ blocks.</p>
1237
+ <p class="last">Default: <code class="docutils literal"><span class="pre">disabled</span></code></p>
1238
+ </td>
1239
+ </tr>
1240
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">ServerAcceptsEmptyAuthId</span></code></td>
1241
+ <td><p class="first">By default, the module will refuse authentication
1242
+ requests that do not contain an auth ID
1243
+ without allowing the request to reach the server.
1244
+ Instead, the module returns an authentication
1245
+ failure to AMPS immediately. This is designed to
1246
+ protect the authentication web service from
1247
+ requests that cannot succeed.</p>
1248
+ <p>In some environments, the web service providing
1249
+ authentication will authenticate a user based
1250
+ entirely on the authentication token provided as
1251
+ the password, and will return the authentication ID
1252
+ for AMPS to use in the permissions document.</p>
1253
+ <p>When this option is set to <code class="docutils literal"><span class="pre">true</span></code>, the module
1254
+ will submit authentication requests to the
1255
+ service even when no authentication ID is
1256
+ provided on the logon request from the AMPS
1257
+ client.</p>
1258
+ <p>An authentication ID is still required
1259
+ for AMPS to be able to track permissions, so
1260
+ when this option is set to <code class="docutils literal"><span class="pre">true</span></code>, the
1261
+ authentication service must set the auth ID
1262
+ in the permissions document when no auth ID is
1263
+ provided in the permissions request. Otherwise,
1264
+ the authentication request will fail.</p>
1265
+ <p class="last">Default: <code class="docutils literal"><span class="pre">false</span></code></p>
1266
+ </td>
1267
+ </tr>
1268
+ </tbody>
1269
+ </table>
1270
+ <p>The following tokens are expanded in the <code class="docutils literal"><span class="pre">HTTPHeader</span></code> element of an
1271
+ authentication request:</p>
1272
+ <table border="1" class="docutils" id="id13">
1273
+ <caption><span class="caption-text"><em>Tokens expanded in HTTPHeader</em></span><a class="headerlink" href="#id13" title="Permalink to this table">¶</a></caption>
1274
+ <colgroup>
1275
+ <col width="50%" />
1276
+ <col width="50%" />
1277
+ </colgroup>
1278
+ <thead valign="bottom">
1279
+ <tr class="row-odd"><th class="head">Authentication Header Token</th>
1280
+ <th class="head">Expansion</th>
1281
+ </tr>
1282
+ </thead>
1283
+ <tbody valign="top">
1284
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AMPS_CLIENT_NAME</span></code></td>
1285
+ <td>Client name provided in the logon request.</td>
1286
+ </tr>
1287
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">AMPS_CONNECTION_NAME</span></code></td>
1288
+ <td>The connection name for the connection
1289
+ requesting logon, as assigned by the AMPS
1290
+ server (based on the transport name).</td>
1291
+ </tr>
1292
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AMPS_CORRELATION_ID</span></code></td>
1293
+ <td>The correlation ID provided on the logon
1294
+ request.</td>
1295
+ </tr>
1296
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">AMPS_MESSAGE_TYPE</span></code></td>
1297
+ <td>The message type of the logon request.</td>
1298
+ </tr>
1299
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AMPS_PASSWORD</span></code></td>
1300
+ <td>The password provided with the logon request.</td>
1301
+ </tr>
1302
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">AMPS_REMOTE_ADDRESS</span></code></td>
1303
+ <td>Remote address from which the logon request
1304
+ was made.</td>
1305
+ </tr>
1306
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AMPS_USER_NAME</span></code></td>
1307
+ <td>User name for the request.</td>
1308
+ </tr>
1309
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">CORRELATION_ID</span></code></td>
1310
+ <td>The correlation ID provided on the logon
1311
+ request. <em>legacy compatibility token</em></td>
1312
+ </tr>
1313
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">USER_NAME</span></code></td>
1314
+ <td>User name for the request.
1315
+ <em>legacy compatibility token</em></td>
1316
+ </tr>
1317
+ </tbody>
1318
+ </table>
1319
+ <p>For <code class="docutils literal"><span class="pre">Entitlement</span></code> blocks, the module requires one of the following two
1320
+ options. These options are used to specify the entitlements to use for
1321
+ the context.</p>
1322
+ <table border="1" class="docutils" id="id14">
1323
+ <caption><span class="caption-text"><em>Entitlement block options</em></span><a class="headerlink" href="#id14" title="Permalink to this table">¶</a></caption>
1324
+ <colgroup>
1325
+ <col width="50%" />
1326
+ <col width="50%" />
1327
+ </colgroup>
1328
+ <thead valign="bottom">
1329
+ <tr class="row-odd"><th class="head">Option</th>
1330
+ <th class="head">Description</th>
1331
+ </tr>
1332
+ </thead>
1333
+ <tbody valign="top">
1334
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">ResourceURI</span></code></td>
1335
+ <td><p class="first">Identifier for the credential store
1336
+ to use for this entitlement context.
1337
+ This is a synonym for the
1338
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> parameter. The
1339
+ module accepts this synonym to make
1340
+ it easier to verify that the
1341
+ <code class="docutils literal"><span class="pre">Entitlement</span></code> context and the
1342
+ <code class="docutils literal"><span class="pre">Authentication</span></code> context use the
1343
+ same values.</p>
1344
+ <p class="last">There is no default for this
1345
+ parameter. Either the
1346
+ <code class="docutils literal"><span class="pre">ResourceURI</span></code> or
1347
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> must be
1348
+ provided. If both are provided, the
1349
+ module uses the value of the
1350
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code>.</p>
1351
+ </td>
1352
+ </tr>
1353
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">CredentialStore</span></code></td>
1354
+ <td><p class="first">Identifier for the entitlement
1355
+ cache. When used for entitlement,
1356
+ this is the name of the entitlement
1357
+ cache that AMPS uses to look up the
1358
+ information.</p>
1359
+ <p class="last">There is no default for this
1360
+ parameter. Either the
1361
+ <code class="docutils literal"><span class="pre">ResourceURI</span></code> or
1362
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> must be
1363
+ provided. If both are provided, the
1364
+ module uses the value of the
1365
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code>.</p>
1366
+ </td>
1367
+ </tr>
1368
+ </tbody>
1369
+ </table>
1370
+ <p>For example, the following configuration loads the module and sets
1371
+ default values that are used for client transports. The module is also
1372
+ used for the admin interface, but that interface uses a separate
1373
+ credential store. Notice that, since the <code class="docutils literal"><span class="pre">HTTPHeader</span></code> options are set
1374
+ when the module is loaded, the custom headers are provided everywhere
1375
+ the module is used, regardless of the <code class="docutils literal"><span class="pre">ResourceURI</span></code> or
1376
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> values.</p>
1377
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
1378
+ <span class="nt">&lt;Modules&gt;</span>
1379
+ ...
1380
+
1381
+ <span class="nt">&lt;Module&gt;</span>
1382
+ <span class="nt">&lt;Name&gt;</span>web-entitlements<span class="nt">&lt;/Name&gt;</span>
1383
+ <span class="nt">&lt;Library&gt;</span>libamps_http_entitlement.so<span class="nt">&lt;/Library&gt;</span>
1384
+
1385
+ <span class="c">&lt;!-- Sets defaults for all uses of the module --&gt;</span>
1386
+ <span class="nt">&lt;Options&gt;</span>
1387
+ <span class="nt">&lt;ResourceURI&gt;</span>http://permissions-server:8080/{{USER_NAME}}.json<span class="nt">&lt;/ResourceURI&gt;</span>
1388
+ <span class="nt">&lt;HTTPHeader&gt;</span>x-tracking-id: {{CORRELATION_ID}}<span class="nt">&lt;/HTTPHeader&gt;</span>
1389
+ <span class="nt">&lt;HTTPHeader&gt;</span>x-origin: AMPS<span class="nt">&lt;/HTTPHeader&gt;</span>
1390
+ <span class="nt">&lt;/Options&gt;</span>
1391
+ <span class="nt">&lt;/Module&gt;</span>
1392
+
1393
+ ...
1394
+ <span class="nt">&lt;/Modules&gt;</span>
1395
+
1396
+ <span class="c">&lt;!-- Use the web-entitlements module with the default values for all authentication and entitlement</span>
1397
+ <span class="c"> unless a transport or the admin interface explicitly sets different values. --&gt;</span>
1398
+ <span class="nt">&lt;Authentication&gt;</span>
1399
+ <span class="nt">&lt;Module&gt;</span>web-entitlements<span class="nt">&lt;/Module&gt;</span>
1400
+ <span class="nt">&lt;/Authentication&gt;</span>
1401
+ <span class="nt">&lt;Entitlement&gt;</span>
1402
+ <span class="nt">&lt;Module&gt;</span>web-entitlements<span class="nt">&lt;/Module&gt;</span>
1403
+ <span class="nt">&lt;/Entitlement&gt;</span>
1404
+
1405
+ <span class="nt">&lt;Admin&gt;</span>
1406
+ <span class="nt">&lt;InetAddr&gt;</span>localhost:8085<span class="nt">&lt;/InetAddr&gt;</span>
1407
+ <span class="c">&lt;!-- enable Basic authentication; see the Monitoring chapter for other options --&gt;</span>
1408
+ <span class="nt">&lt;WWWAuthenticate&gt;</span>Basic realm=&quot;AMPS Admin&quot;<span class="nt">&lt;/WWWAuthenticate&gt;</span>
1409
+ <span class="c">&lt;!-- Use the web-entitlements module, but set a different URI and credential store for the admin</span>
1410
+ <span class="c"> interface. --&gt;</span>
1411
+ <span class="nt">&lt;Authentication&gt;</span>
1412
+ <span class="nt">&lt;Module&gt;</span>web-entitlements<span class="nt">&lt;/Module&gt;</span>
1413
+ <span class="nt">&lt;Options&gt;</span>
1414
+ <span class="nt">&lt;CredentialStore&gt;</span>AdminCreds<span class="nt">&lt;/CredentialStore&gt;</span>
1415
+ <span class="nt">&lt;ResourceURI&gt;</span>http://permissions-server:8080/admin/{{USER_NAME}}.json<span class="nt">&lt;/ResourceURI&gt;</span>
1416
+ <span class="nt">&lt;/Options&gt;</span>
1417
+ <span class="nt">&lt;/Authentication&gt;</span>
1418
+ <span class="nt">&lt;Entitlement&gt;</span>
1419
+ <span class="nt">&lt;Module&gt;</span>web-entitlements<span class="nt">&lt;/Module&gt;</span>
1420
+ <span class="nt">&lt;Options&gt;</span>
1421
+ <span class="nt">&lt;ResourceURI&gt;</span>http://permissions-server:8080/admin/{{USER_NAME}}.json<span class="nt">&lt;/ResourceURI&gt;</span>
1422
+ <span class="nt">&lt;CredentialStore&gt;</span>AdminCreds<span class="nt">&lt;/CredentialStore&gt;</span>
1423
+ <span class="nt">&lt;/Options&gt;</span>
1424
+ <span class="nt">&lt;/Entitlement&gt;</span>
1425
+ <span class="nt">&lt;/Admin&gt;</span>
1426
+
1427
+ <span class="c">&lt;!-- All of these transports use the Authentication and Entitlement set at the instance level. --&gt;</span>
1428
+ <span class="nt">&lt;Transports&gt;</span>
1429
+ <span class="nt">&lt;Transport&gt;</span>
1430
+ <span class="nt">&lt;Name&gt;</span>json-tcp<span class="nt">&lt;/Name&gt;</span>
1431
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
1432
+ <span class="nt">&lt;InetAddr&gt;</span>9007<span class="nt">&lt;/InetAddr&gt;</span>
1433
+ <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
1434
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
1435
+ <span class="nt">&lt;/Transport&gt;</span>
1436
+ <span class="nt">&lt;Transport&gt;</span>
1437
+ <span class="nt">&lt;Name&gt;</span>any-tcp<span class="nt">&lt;/Name&gt;</span>
1438
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
1439
+ <span class="nt">&lt;InetAddr&gt;</span>9090<span class="nt">&lt;/InetAddr&gt;</span>
1440
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
1441
+ <span class="nt">&lt;/Transport&gt;</span>
1442
+ <span class="nt">&lt;/Transports&gt;</span>
1443
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
1444
+ </pre></div>
1445
+ </div>
1446
+ <div class="section" id="using-https-for-authentication-and-entitlement-requests">
1447
+ <h4>Using HTTPS for Authentication and Entitlement Requests<a class="headerlink" href="#using-https-for-authentication-and-entitlement-requests" title="Permalink to this headline">¶</a></h4>
1448
+ <p>The Web Service Authentication and Entitlement Module optionally
1449
+ supports <code class="docutils literal"><span class="pre">https</span></code> entitlement requests. When the <code class="docutils literal"><span class="pre">ResourceURI</span></code> uses <code class="docutils literal"><span class="pre">https</span></code>
1450
+ as the scheme, the module will attempt to use <code class="docutils literal"><span class="pre">https</span></code> to connect to the
1451
+ web service.</p>
1452
+ <p>By default, the module attempts to verify the identity of the remote web
1453
+ service, which requires a key file containing the key for the
1454
+ certificate authority that signed the certificate for the remote web
1455
+ service.</p>
1456
+ <p>AMPS does not require that the certificate and key provided for outgoing
1457
+ <code class="docutils literal"><span class="pre">https</span></code> requests be the same certificates used for incoming SSL
1458
+ connections to AMPS. However, if you have configured AMPS to accept SSL
1459
+ connections from AMPS clients, the certificates you use for those
1460
+ connections are often suitable for outgoing web authentication module
1461
+ connections, and the same certificates can be provided in both sections
1462
+ of the configuration file.</p>
1463
+ <table border="1" class="docutils" id="id15">
1464
+ <caption><span class="caption-text"><em>HTTPS options</em></span><a class="headerlink" href="#id15" title="Permalink to this table">¶</a></caption>
1465
+ <colgroup>
1466
+ <col width="50%" />
1467
+ <col width="50%" />
1468
+ </colgroup>
1469
+ <thead valign="bottom">
1470
+ <tr class="row-odd"><th class="head">Option</th>
1471
+ <th class="head">Description</th>
1472
+ </tr>
1473
+ </thead>
1474
+ <tbody valign="top">
1475
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Certificate</span></code></td>
1476
+ <td><p class="first">The certificate to use for the AMPS
1477
+ connection to the web service. When
1478
+ configured, this certificate can be
1479
+ provided to the web service if the
1480
+ web service requests client
1481
+ authentication for the connection.</p>
1482
+ <p class="last">There is no default for this
1483
+ parameter.</p>
1484
+ </td>
1485
+ </tr>
1486
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">Key</span></code></td>
1487
+ <td><p class="first">The key file to use for the AMPS
1488
+ connection to the web service. When
1489
+ configured, this key can be used
1490
+ for client authentication if the
1491
+ web service requests client
1492
+ authentication for the connection.</p>
1493
+ <p class="last">There is no default for this
1494
+ parameter.</p>
1495
+ </td>
1496
+ </tr>
1497
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">CAKey</span></code></td>
1498
+ <td><p class="first">The certificate authority key. When
1499
+ configured, this key can be used
1500
+ for the AMPS server to verify the
1501
+ identity of the web service.</p>
1502
+ <p class="last">There is no default for this
1503
+ parameter. The <code class="docutils literal"><span class="pre">CAKey</span></code> must be
1504
+ provided when
1505
+ <code class="docutils literal"><span class="pre">AllowUnverfiedPeer</span></code> is set to
1506
+ <code class="docutils literal"><span class="pre">false</span></code>, the default.</p>
1507
+ </td>
1508
+ </tr>
1509
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">AllowUnverifiedPeer</span></code></td>
1510
+ <td><p class="first">Specifies whether AMPS requires the
1511
+ web service to identify itself.
1512
+ When this is set to false, the
1513
+ default, AMPS requires that the web
1514
+ service provides a certificate that
1515
+ can be verified with the configured
1516
+ <code class="docutils literal"><span class="pre">CAKey</span></code>.</p>
1517
+ <p class="last">Default: <code class="docutils literal"><span class="pre">false</span></code></p>
1518
+ </td>
1519
+ </tr>
1520
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AllowSelfSigned</span></code></td>
1521
+ <td><p class="first">Specifies whether AMPS will accept
1522
+ self-signed certificates for
1523
+ <code class="docutils literal"><span class="pre">https</span></code> connections.</p>
1524
+ <p class="last">Default: <code class="docutils literal"><span class="pre">false</span></code></p>
1525
+ </td>
1526
+ </tr>
1527
+ </tbody>
1528
+ </table>
1529
+ <p>The following configuration file shows a common way to configure the
1530
+ module for testing purposes when working with a server that accepts
1531
+ <code class="docutils literal"><span class="pre">https</span></code> connections. While the outgoing connection will use SSL, the
1532
+ module will not provide certificates to the server, or request that the
1533
+ server verify its identity.</p>
1534
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Module&gt;</span>
1535
+ <span class="nt">&lt;Name&gt;</span>web-entitlements<span class="nt">&lt;/Name&gt;</span>
1536
+ <span class="nt">&lt;Library&gt;</span>libamps_http_entitlement.so<span class="nt">&lt;/Library&gt;</span>
1537
+ <span class="nt">&lt;Options&gt;</span>
1538
+ <span class="nt">&lt;ResourceURI&gt;</span>https://permissions-server:443/{{USER_NAME}}.json<span class="nt">&lt;/ResourceURI&gt;</span>
1539
+ <span class="nt">&lt;AllowUnverifiedPeer&gt;</span>true<span class="nt">&lt;/AllowUnverifiedPeer&gt;</span>
1540
+ <span class="nt">&lt;AllowSelfSigned&gt;</span>true<span class="nt">&lt;/AllowSelfSigned&gt;</span>
1541
+ <span class="nt">&lt;/Options&gt;</span>
1542
+ <span class="nt">&lt;/Module&gt;</span>
1543
+ </pre></div>
1544
+ </div>
1545
+ <p>The following configuration file demonstrates how to configure the
1546
+ module to verify the identity of the remote server, provide verification
1547
+ of the AMPS server identity to that server, and require that all
1548
+ certificates be signed by a certificate authority.</p>
1549
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Module&gt;</span>
1550
+ <span class="nt">&lt;Name&gt;</span>web-entitlements<span class="nt">&lt;/Name&gt;</span>
1551
+ <span class="nt">&lt;Library&gt;</span>libamps_http_entitlement.so<span class="nt">&lt;/Library&gt;</span>
1552
+ <span class="nt">&lt;Options&gt;</span>
1553
+ <span class="nt">&lt;ResourceURI&gt;</span>https://permissions-server:443/{{USER_NAME}}.json<span class="nt">&lt;/ResourceURI&gt;</span>
1554
+ <span class="nt">&lt;Certificate&gt;</span>/etc/security/amps-cert.pem<span class="nt">&lt;/Certificate&gt;</span>
1555
+ <span class="nt">&lt;Key&gt;</span>/etc/security/amps-key.pem<span class="nt">&lt;/Key&gt;</span>
1556
+ <span class="nt">&lt;CAKey&gt;</span>/etc/security/ca.pem<span class="nt">&lt;/CAKey&gt;</span>
1557
+ <span class="nt">&lt;/Options&gt;</span>
1558
+ <span class="nt">&lt;/Module&gt;</span>
1559
+ </pre></div>
1560
+ </div>
1561
+ </div>
1562
+ </div>
1563
+ <div class="section" id="permissions-management-and-request-flow">
1564
+ <h3>Permissions Management and Request Flow<a class="headerlink" href="#permissions-management-and-request-flow" title="Permalink to this headline">¶</a></h3>
1565
+ <p>This section describes the request flow for the Web Service
1566
+ Authentication and Entitlement Module when used in the default mode.</p>
1567
+ <p>Notice that authentication and entitlement are two separate steps. The
1568
+ module obtains the set of permissions during the authentication step,
1569
+ and then provides responses to AMPS entitlement requests during the
1570
+ entitlement step. What this means is that, in the default mode,
1571
+ a user must have authenticated using the module for an entitlement request to be allowed.</p>
1572
+ <div class="section" id="authentication-step">
1573
+ <h4>Authentication Step<a class="headerlink" href="#authentication-step" title="Permalink to this headline">¶</a></h4>
1574
+ <ol class="arabic simple">
1575
+ <li>Logon request received from the client.</li>
1576
+ <li>Module requests an entitlement document (via <code class="docutils literal"><span class="pre">GET</span></code>) from a
1577
+ specified Web Service. The credentials in the logon request are
1578
+ provided as the credentials for the <code class="docutils literal"><span class="pre">GET</span></code>. The module supports
1579
+ both Basic and Digest authentication to the Web Service, as
1580
+ described in RFC 7616 (HTTP digest access authentication) and
1581
+ RFC 7617 (The &#8216;Basic&#8217; HTTP authentication scheme).</li>
1582
+ <li>If AMPS cannot retrieve the entitlement document using the provided
1583
+ credentials, AMPS returns a failure for the logon request.</li>
1584
+ <li>If the Web Service Authentication and Entitlement module already has
1585
+ a parsed entitlement document for this user in the
1586
+ <code class="docutils literal"><span class="pre">CredentialStore</span></code> for this request, the module simply returns
1587
+ success for the authentication request.</li>
1588
+ <li>Otherwise, the module parses the entitlement document and stores the
1589
+ entitlements in the <code class="docutils literal"><span class="pre">CredentialStore</span></code>. If the module can&#8217;t
1590
+ successfully parse the document, it returns a failure for the
1591
+ authentication request.</li>
1592
+ </ol>
1593
+ </div>
1594
+ <div class="section" id="entitlement-step">
1595
+ <h4>Entitlement Step<a class="headerlink" href="#entitlement-step" title="Permalink to this headline">¶</a></h4>
1596
+ <ol class="arabic simple">
1597
+ <li>The module looks up the user name in the <code class="docutils literal"><span class="pre">CredentialStore</span></code> for the
1598
+ request. If the module has no stored entitlements for the user, the
1599
+ module denies the request.</li>
1600
+ <li>The module looks for a matching entitlement. Entitlements for a user
1601
+ are searched in exactly the same order in which they appear in the
1602
+ document. The module uses the first entitlement that matches the
1603
+ request. If no entitlements match, the module denies the request.</li>
1604
+ <li>The module checks the entitlement to see if the entitlement grants
1605
+ access to the user or disallows access to the user. If the
1606
+ entitlement disallows access, the module denies the request.</li>
1607
+ <li>The module allows the request and applies any filter specified in the
1608
+ matching entitlement.</li>
1609
+ </ol>
1610
+ </div>
1611
+ <div class="section" id="entitlement-reset">
1612
+ <h4>Entitlement Reset<a class="headerlink" href="#entitlement-reset" title="Permalink to this headline">¶</a></h4>
1613
+ <p>The module caches the set of entitlements for a user while that user is
1614
+ connected. As described in the previous section, the module parses
1615
+ the returned permissions document if the module does not have an
1616
+ existing set of entitlements for that user or if the <code class="docutils literal"><span class="pre">EntitlementTimeout</span></code>
1617
+ has expired and the document has changed.</p>
1618
+ <p>The module provides two mechanisms for automatically resetting
1619
+ the entitlement cache and updating permissions for the user:</p>
1620
+ <ol class="arabic">
1621
+ <li><p class="first">The module provides &#8220;reset cache on disconnect&#8221; entitlement
1622
+ behavior when in authentication and entitlement mode. The module resets
1623
+ both the AMPS entitlement cache and the information on the parsed permissions
1624
+ document for a given user when all of the connections for that user are
1625
+ closed. In practical terms, this means that changing the entitlement
1626
+ document returned by the web service has no immediate effect on the
1627
+ permission set that AMPS enforces. AMPS will continue to use the permissions
1628
+ in the document returned from the first logon request for that user until
1629
+ all connections for that user have been closed. When used in authentication
1630
+ and entitlement mode, this functionality is always active; when the last
1631
+ connection for a given user disconnects, the AMPS entitlement cache and
1632
+ the module entitlements are reset.</p>
1633
+ <p>Notice that this also means that if AMPS entitlements are reset
1634
+ for a user (for example, using the <code class="docutils literal"><span class="pre">amps-action-do-reset-entitlement</span></code>
1635
+ action), this will also clear the module cache, since all connections
1636
+ for that user will be closed. Likewise, a user can always update
1637
+ permissions by completely logging out of AMPS and then logging back
1638
+ in.</p>
1639
+ </li>
1640
+ <li><p class="first">Optionally, the module can set an <code class="docutils literal"><span class="pre">EntitlementTimeout</span></code>. When this is
1641
+ set, a change to the user permissions after the timeout period will
1642
+ reset any current connections for that user, clear the AMPS entitlement
1643
+ cache, and replace existing permissions with the contents of the
1644
+ permissions document returned.</p>
1645
+ </li>
1646
+ </ol>
1647
+ <div class="admonition tip">
1648
+ <p class="first admonition-title">Tip</p>
1649
+ <p class="last">This functionality is not available when
1650
+ the module is in <code class="docutils literal"><span class="pre">EntitlementOnly</span></code> mode, as described below. When
1651
+ used in <code class="docutils literal"><span class="pre">EntitlementOnly</span></code> mode, the module does not track connection
1652
+ or disconnection, so entitlements are cached in the module for the
1653
+ lifetime of the instance.</p>
1654
+ </div>
1655
+ </div>
1656
+ <div class="section" id="entitlement-only-mode">
1657
+ <h4>Entitlement Only Mode<a class="headerlink" href="#entitlement-only-mode" title="Permalink to this headline">¶</a></h4>
1658
+ <p>Starting in AMPS 5.3.1, the HTTP authentication and entitlements module supports
1659
+ a mode where another module can be used for authentication, and this module
1660
+ can be used for entitlements. To enable this mode, include the following
1661
+ configuration item in the <code class="docutils literal"><span class="pre">Modules</span></code> block that loads the module:</p>
1662
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Options&gt;</span>
1663
+ <span class="c">&lt;!-- other options here --&gt;</span>
1664
+ <span class="nt">&lt;EntitlementOnly/&gt;</span>
1665
+ <span class="nt">&lt;/Options&gt;</span>
1666
+ </pre></div>
1667
+ </div>
1668
+ <p>When an <code class="docutils literal"><span class="pre">EntitlementOnly</span></code> element is provided, the module cannot be used
1669
+ to authenticate users. Instead, the module makes an <em>unauthenticated</em> HTTP
1670
+ request the first time that permissions are requested for a given user ID.
1671
+ The permissions document returned is cached, and used for subsequent requests.</p>
1672
+ <p>When using the module in this mode, the module may not be used in an
1673
+ <code class="docutils literal"><span class="pre">Authentication</span></code> block. The module configuration or <code class="docutils literal"><span class="pre">Entitlement</span></code> block
1674
+ configuration must provide a <code class="docutils literal"><span class="pre">ResourceURI</span></code>, and may provide the other
1675
+ options normally accepted in the <code class="docutils literal"><span class="pre">Authentication</span></code> block (for example,
1676
+ <code class="docutils literal"><span class="pre">HTTPHeader</span></code>, <code class="docutils literal"><span class="pre">RetryCount</span></code>, and so on).</p>
1677
+ <p>In this mode, the module does not see connect and logon requests. Therefore,
1678
+ the module does not provide automatic entitlement cache reset in this mode
1679
+ and the module caches the permissions for a given user in a given
1680
+ credential store for the lifetime of the instance.</p>
1681
+ </div>
1682
+ <div class="section" id="entitlement-only-request-flow">
1683
+ <h4>Entitlement Only Request Flow<a class="headerlink" href="#entitlement-only-request-flow" title="Permalink to this headline">¶</a></h4>
1684
+ <p>This section describes the request flow when the module is operating
1685
+ in entitlement only mode. This is very similar to the flow in the
1686
+ default mode, except that all of the processing happens as a part of
1687
+ the first entitlement request for a given user ID, and no credential
1688
+ information is available for the request to the HTTP server.</p>
1689
+ <ol class="arabic simple">
1690
+ <li>Entitlement request is received from AMPS.</li>
1691
+ <li>The module looks up the user name in the <code class="docutils literal"><span class="pre">CredentialStore</span></code> for the
1692
+ request. If the module has stored entitlements for the user, the
1693
+ module proceeds to step 6.</li>
1694
+ <li>Module requests an entitlement document (via <code class="docutils literal"><span class="pre">GET</span></code>) from a
1695
+ specified Web Service. No credentials are provided on this request.</li>
1696
+ <li>If the module cannot retrieve the entitlement document, the module returns
1697
+ a failure for the entitlement request.</li>
1698
+ <li>The module parses the returned permissions document. If an error occurs while
1699
+ parsing the permissions document, the module returns a failure for the
1700
+ entitlement request. Otherwise, the module loads the parsed permissions
1701
+ into the <code class="docutils literal"><span class="pre">CredentialStore</span></code>.</li>
1702
+ <li>The module uses the <code class="docutils literal"><span class="pre">CredentialStore</span></code> to look for a matching entitlement.
1703
+ Entitlements for a user are searched in exactly the same order in which they
1704
+ appear in the document. The module uses the first entitlement that matches
1705
+ the request. If no entitlements match, the module denies the request.</li>
1706
+ <li>The module checks the entitlement to see if the entitlement grants
1707
+ access to the user or disallows access to the user. If the
1708
+ entitlement disallows access, the module denies the request.</li>
1709
+ <li>If the module allows the request, any filters specified in the matching
1710
+ entitlement are applied.</li>
1711
+ </ol>
1712
+ </div>
1713
+ </div>
1714
+ </div>
1715
+ <div class="section" id="authentication-with-the-amps-multimechanism-authentication-module">
1716
+ <span id="ug-multimechanism-authentication"></span><span id="ug-multi-authentication"></span><h2>Authentication with the AMPS Multimechanism Authentication Module<a class="headerlink" href="#authentication-with-the-amps-multimechanism-authentication-module" title="Permalink to this headline">¶</a></h2>
1717
+ <p>AMPS includes a module that supports the commonly used infrastructure
1718
+ for enterprise authentication. In this release, the module includes
1719
+ support for LDAP or Kerberos authentication.</p>
1720
+ <p>In this release, the multimechanism authentication module is provided with AMPS,
1721
+ but is not loaded by default. This module is an optional extension to
1722
+ the AMPS product, and while it is included with the AMPS distribution,
1723
+ the module must be explicitly loaded, enabled, and configured.</p>
1724
+ <p>This module provides authentication, but does not provide an entitlement
1725
+ mechanism. When planning a strategy for securing AMPS using this module,
1726
+ you will also need to plan a strategy to manage entitlements.</p>
1727
+ <div class="section" id="when-to-use-the-multimechanism-authentication-module">
1728
+ <h3>When to Use the Multimechanism Authentication Module<a class="headerlink" href="#when-to-use-the-multimechanism-authentication-module" title="Permalink to this headline">¶</a></h3>
1729
+ <p>60East recommends using this module when integrating AMPS authentication
1730
+ into an existing infrastructure. If your environment does not have an
1731
+ existing infrastructure that offers one of the authentication methods
1732
+ supported by this module, it is typically easier to use the HTTP
1733
+ authentication and entitlement module than it is to implement or deploy
1734
+ a new authentication system.</p>
1735
+ <p>The AMPS Multimechanism authentication module can be a good option when:</p>
1736
+ <ul class="simple">
1737
+ <li>The site has an existing authentication infrastructure for users
1738
+ that need to be authenticated to AMPS, and that infrastructure supports
1739
+ authentication using:<ul>
1740
+ <li>Kerberos, <em>or</em></li>
1741
+ <li>LDAP</li>
1742
+ </ul>
1743
+ </li>
1744
+ <li>The authentication infrastructure is relatively stable and well-supported,
1745
+ with support for adding AMPS to the set of applications that use
1746
+ this infrastructure</li>
1747
+ </ul>
1748
+ </div>
1749
+ <div class="section" id="setting-authentication-mechanisms">
1750
+ <h3>Setting Authentication Mechanisms<a class="headerlink" href="#setting-authentication-mechanisms" title="Permalink to this headline">¶</a></h3>
1751
+ <p>To enable a particular authentication mechanism in the
1752
+ multimechanism authentication module, you simply provide
1753
+ configuration parameters for that mechanism.</p>
1754
+ <p>For example, if you provide configuration parameters for an
1755
+ LDAP server, the module will enable LDAP. If you provide
1756
+ configuration parameters for Kerberos, the module will enable
1757
+ Kerberos.</p>
1758
+ <p>When more than one authentication mechanism is enabled, the
1759
+ module will attempt to detect the authentication mechanism used
1760
+ for a given logon request based on the credentials provided. If
1761
+ the module cannot determine the mechanism to use for a given request,
1762
+ and there is more than one mechanism configured,
1763
+ the module defaults to the mechanism specified in the
1764
+ <code class="docutils literal"><span class="pre">DefaultAuthenticationMechanism</span></code> in the module options.</p>
1765
+ <p>Notice, however, that the module does not allow a mechanism that
1766
+ accepts arbitrary passwords (in this release, LDAP) to be configured
1767
+ with a mechanism that accepts passwords of a specific format (in this
1768
+ release, Kerberos). In this release, the practical result is that a
1769
+ given module can be configured to use Kerberos <em>or</em> LDAP for authentication,
1770
+ but cannot be configured to use both.</p>
1771
+ </div>
1772
+ <div class="section" id="configuring-amps-to-use-the-multimechanism-authentication-module">
1773
+ <h3>Configuring AMPS to use the Multimechanism Authentication Module<a class="headerlink" href="#configuring-amps-to-use-the-multimechanism-authentication-module" title="Permalink to this headline">¶</a></h3>
1774
+ <p>The multimechanism authentication module is included in the AMPS
1775
+ distribution, but is not loaded in AMPS by default. To load the
1776
+ module, add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code> block
1777
+ in your AMPS configuration:</p>
1778
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
1779
+ ...
1780
+
1781
+ <span class="nt">&lt;Module&gt;</span>
1782
+ <span class="nt">&lt;Name&gt;</span>multimech-authentication<span class="nt">&lt;/Name&gt;</span>
1783
+ <span class="nt">&lt;Library&gt;</span>libamps_multi_authentication.so<span class="nt">&lt;/Library&gt;</span>
1784
+ <span class="nt">&lt;/Module&gt;</span>
1785
+
1786
+ ...
1787
+ <span class="nt">&lt;/Modules&gt;</span>
1788
+ </pre></div>
1789
+ </div>
1790
+ <p>This module does not require any options as part of the module configuration
1791
+ and ignores any options provided when the module is loaded.</p>
1792
+ <p>This module supports the following options when used in an <code class="docutils literal"><span class="pre">Authentication</span></code>
1793
+ block:</p>
1794
+ <p><strong>Kerberos Options</strong></p>
1795
+ <table border="1" class="docutils" id="id16">
1796
+ <caption><span class="caption-text"><em>Kerberos options for Multimechanism Authentication</em></span><a class="headerlink" href="#id16" title="Permalink to this table">¶</a></caption>
1797
+ <colgroup>
1798
+ <col width="50%" />
1799
+ <col width="50%" />
1800
+ </colgroup>
1801
+ <thead valign="bottom">
1802
+ <tr class="row-odd"><th class="head">Option</th>
1803
+ <th class="head">Description</th>
1804
+ </tr>
1805
+ </thead>
1806
+ <tbody valign="top">
1807
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Kerberos.Keytab</span></code></td>
1808
+ <td><p class="first">Sets a keytab file to use for Kerberos authentication.
1809
+ This option must be set to the path of the file, which
1810
+ can be either an absolute path or a relative path
1811
+ based on the current working directory of the AMPS
1812
+ server process.</p>
1813
+ <p>When this option is specified, the module will provide
1814
+ Kerberos authentication and a <code class="docutils literal"><span class="pre">Kerberos.SPN</span></code> must
1815
+ be specified.</p>
1816
+ <p class="last">There is no default for this parameter.</p>
1817
+ </td>
1818
+ </tr>
1819
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">Kerberos.SPN</span></code></td>
1820
+ <td><p class="first">Sets the Service Principal Name (SPN) to use for
1821
+ Kerberos authentication.</p>
1822
+ <p>When this option is specified, the module will provide
1823
+ Kerberos authentication and a <code class="docutils literal"><span class="pre">Kerberos.Keytab</span></code> must
1824
+ be specified.</p>
1825
+ <p class="last">There is no default for this parameter.</p>
1826
+ </td>
1827
+ </tr>
1828
+ </tbody>
1829
+ </table>
1830
+ <p><strong>LDAP Options</strong></p>
1831
+ <table border="1" class="docutils" id="id17">
1832
+ <caption><span class="caption-text"><em>LDAP options for Multimechanism Authentication</em></span><a class="headerlink" href="#id17" title="Permalink to this table">¶</a></caption>
1833
+ <colgroup>
1834
+ <col width="50%" />
1835
+ <col width="50%" />
1836
+ </colgroup>
1837
+ <thead valign="bottom">
1838
+ <tr class="row-odd"><th class="head">Option</th>
1839
+ <th class="head">Description</th>
1840
+ </tr>
1841
+ </thead>
1842
+ <tbody valign="top">
1843
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">LDAP.Host</span></code></td>
1844
+ <td><p class="first">Sets the host name to use for LDAP authentication.</p>
1845
+ <p>When this option is specified, the module will
1846
+ provide LDAP authentication. This parameter is
1847
+ required if any other <code class="docutils literal"><span class="pre">LDAP</span></code> parameter is specified.</p>
1848
+ <p class="last">There is no default for this parameter.</p>
1849
+ </td>
1850
+ </tr>
1851
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">LDAP.Port</span></code></td>
1852
+ <td><p class="first">Sets the port number to use for LDAP authentication.</p>
1853
+ <p>When this option is specified, the module will
1854
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Host</span></code>
1855
+ must also be specified.</p>
1856
+ <p class="last">Default: <code class="docutils literal"><span class="pre">389</span></code></p>
1857
+ </td>
1858
+ </tr>
1859
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">LDAP.ProtocolVersion</span></code></td>
1860
+ <td><p class="first">Sets the version of the LDAP protocol to use.</p>
1861
+ <p>When this option is specified, the module will
1862
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Host</span></code>
1863
+ must also be specified.</p>
1864
+ <p class="last">Default: <code class="docutils literal"><span class="pre">2</span></code></p>
1865
+ </td>
1866
+ </tr>
1867
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">LDAP.BaseDN</span></code></td>
1868
+ <td><p class="first">Sets the base Distinguished Name (DN) to use for
1869
+ LDAP authentication.</p>
1870
+ <p>When this option is specified, the module will
1871
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Host</span></code>
1872
+ must also be specified.</p>
1873
+ <p class="last">This parameter defaults to an empty string.</p>
1874
+ </td>
1875
+ </tr>
1876
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">LDAP.ServiceAccountDN</span></code></td>
1877
+ <td><p class="first">Sets the Distinguished Name (DN) for the service
1878
+ account to use for LDAP authentication.</p>
1879
+ <p>When this option is specified, the module will
1880
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Host</span></code>
1881
+ must also be specified.</p>
1882
+ <p class="last">This parameter defaults to an empty string.</p>
1883
+ </td>
1884
+ </tr>
1885
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">LDAP.ServiceAccountPasswordFile</span></code></td>
1886
+ <td><p class="first">Sets a file from which to read the password for the
1887
+ service account to use for LDAP authentication.</p>
1888
+ <p>When this option is specified, the module will
1889
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Host</span></code>
1890
+ must also be specified.</p>
1891
+ <p class="last">This parameter defaults to an empty string, which
1892
+ specifies that no password will be provided.</p>
1893
+ </td>
1894
+ </tr>
1895
+ </tbody>
1896
+ </table>
1897
+ <p><strong>General Options</strong></p>
1898
+ <table border="1" class="docutils" id="id18">
1899
+ <caption><span class="caption-text"><em>General policy options for Multimechanism Authentication</em></span><a class="headerlink" href="#id18" title="Permalink to this table">¶</a></caption>
1900
+ <colgroup>
1901
+ <col width="50%" />
1902
+ <col width="50%" />
1903
+ </colgroup>
1904
+ <thead valign="bottom">
1905
+ <tr class="row-odd"><th class="head">Option</th>
1906
+ <th class="head">Description</th>
1907
+ </tr>
1908
+ </thead>
1909
+ <tbody valign="top">
1910
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AllowAnonymous</span></code></td>
1911
+ <td><p class="first">When set to <code class="docutils literal"><span class="pre">enabled</span></code>, allows users to logon
1912
+ without providing a password. In this case, however,
1913
+ the authenticated username will be set to an empty
1914
+ string.</p>
1915
+ <p class="last">Default: <code class="docutils literal"><span class="pre">disabled</span></code></p>
1916
+ </td>
1917
+ </tr>
1918
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">DefaultAuthenticationMechanism</span></code></td>
1919
+ <td><p class="first">When provided, sets the authentication mechanism to
1920
+ use if AMPS cannot identify the type of authentication
1921
+ token provided by the connection.</p>
1922
+ <p>In this release, the value for this parameter can be
1923
+ either <code class="docutils literal"><span class="pre">Kerberos</span></code> or <code class="docutils literal"><span class="pre">LDAP</span></code>.</p>
1924
+ <p class="last">There is no default for this option. If no
1925
+ <code class="docutils literal"><span class="pre">DefaultAuthenticationMechanism</span></code> is configured and
1926
+ AMPS cannot identify the type of authentication token
1927
+ provided by a connection, AMPS reports an error for
1928
+ that logon.</p>
1929
+ </td>
1930
+ </tr>
1931
+ </tbody>
1932
+ </table>
1933
+ <p>The module must be configured with at least one authentication method. Otherwise, the module fails to initialize and AMPS will halt the startup process.</p>
1934
+ <p>For example, the following configuration loads the module and configures
1935
+ the module to use LDAP authentication by contacting the server
1936
+ <code class="docutils literal"><span class="pre">myenterprise-auth-server</span></code> on port <code class="docutils literal"><span class="pre">9389</span></code>. In this case, the
1937
+ LDAP server does not require authentication. Otherwise, the
1938
+ configuration would provide the service account DN and
1939
+ password for the server.</p>
1940
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
1941
+
1942
+ <span class="nt">&lt;Modules&gt;</span>
1943
+ ...
1944
+
1945
+ <span class="nt">&lt;Module&gt;</span>
1946
+ <span class="nt">&lt;Name&gt;</span>multi-auth<span class="nt">&lt;/Name&gt;</span>
1947
+ <span class="nt">&lt;Library&gt;</span>libamps_multi_authentication.so<span class="nt">&lt;/Library&gt;</span>
1948
+ <span class="nt">&lt;/Module&gt;</span>
1949
+
1950
+ ...
1951
+ <span class="nt">&lt;/Modules&gt;</span>
1952
+
1953
+ <span class="nt">&lt;Authentication&gt;</span>
1954
+ <span class="nt">&lt;Module&gt;</span>multi-auth<span class="nt">&lt;/Module&gt;</span>
1955
+ <span class="nt">&lt;Options&gt;</span>
1956
+ <span class="nt">&lt;LDAP.Host&gt;</span>myenterprise-auth-server<span class="nt">&lt;/LDAP.Host&gt;</span>
1957
+ <span class="nt">&lt;LDAP.Port&gt;</span>9389<span class="nt">&lt;/LDAP.Port&gt;</span>
1958
+ <span class="nt">&lt;/Options&gt;</span>
1959
+ <span class="nt">&lt;/Authentication&gt;</span>
1960
+
1961
+
1962
+ <span class="c">&lt;!-- The Admin module uses the LDAP server configured above for</span>
1963
+ <span class="c"> authentication. --&gt;</span>
1964
+ <span class="nt">&lt;Admin&gt;</span>
1965
+ <span class="nt">&lt;InetAddr&gt;</span>localhost:8085<span class="nt">&lt;/InetAddr&gt;</span>
1966
+ <span class="nt">&lt;/Admin&gt;</span>
1967
+
1968
+ <span class="c">&lt;!-- Both of these transports use the LDAP server configured above</span>
1969
+ <span class="c"> for authentication. --&gt;</span>
1970
+ <span class="nt">&lt;Transports&gt;</span>
1971
+ <span class="nt">&lt;Transport&gt;</span>
1972
+ <span class="nt">&lt;Name&gt;</span>json-tcp<span class="nt">&lt;/Name&gt;</span>
1973
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
1974
+ <span class="nt">&lt;InetAddr&gt;</span>9007<span class="nt">&lt;/InetAddr&gt;</span>
1975
+ <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
1976
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
1977
+ <span class="nt">&lt;/Transport&gt;</span>
1978
+ <span class="nt">&lt;Transport&gt;</span>
1979
+ <span class="nt">&lt;Name&gt;</span>any-tcp<span class="nt">&lt;/Name&gt;</span>
1980
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
1981
+ <span class="nt">&lt;InetAddr&gt;</span>9090<span class="nt">&lt;/InetAddr&gt;</span>
1982
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
1983
+ <span class="nt">&lt;/Transport&gt;</span>
1984
+ <span class="nt">&lt;/Transports&gt;</span>
1985
+
1986
+ <span class="c">&lt;!-- other configuration here --&gt;</span>
1987
+
1988
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
1989
+ </pre></div>
1990
+ </div>
1991
+ <p>The configuration below loads the module and configures the module
1992
+ to use Kerberos for clients that provide a Kerberos token on logon.
1993
+ For Kerberos, AMPS will use the SPN <cite>AMPS/host.domain.com</cite> and the
1994
+ keytab file at <cite>/path/to/amps.keytab</cite>.</p>
1995
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
1996
+
1997
+ <span class="nt">&lt;Modules&gt;</span>
1998
+ ...
1999
+
2000
+ <span class="nt">&lt;Module&gt;</span>
2001
+ <span class="nt">&lt;Name&gt;</span>multi-auth<span class="nt">&lt;/Name&gt;</span>
2002
+ <span class="nt">&lt;Library&gt;</span>libamps_multi_authentication.so<span class="nt">&lt;/Library&gt;</span>
2003
+ <span class="nt">&lt;/Module&gt;</span>
2004
+
2005
+ ...
2006
+ <span class="nt">&lt;/Modules&gt;</span>
2007
+
2008
+ <span class="nt">&lt;Authentication&gt;</span>
2009
+ <span class="nt">&lt;Module&gt;</span>multi-auth<span class="nt">&lt;/Module&gt;</span>
2010
+ <span class="nt">&lt;Options&gt;</span>
2011
+ <span class="nt">&lt;Kerberos.SPN&gt;</span>AMPS/host.domain.com<span class="nt">&lt;/Kerberos.SPN&gt;</span>
2012
+ <span class="nt">&lt;Kerberos.Keytab&gt;</span>/path/to/amps.keytab<span class="nt">&lt;/Kerberos.Keytab&gt;</span>
2013
+ <span class="nt">&lt;/Options&gt;</span>
2014
+ <span class="nt">&lt;/Authentication&gt;</span>
2015
+
2016
+
2017
+ <span class="c">&lt;!-- The Admin module uses the Kerberos configuration</span>
2018
+ <span class="c"> above for authentication. --&gt;</span>
2019
+ <span class="nt">&lt;Admin&gt;</span>
2020
+ <span class="nt">&lt;InetAddr&gt;</span>localhost:8085<span class="nt">&lt;/InetAddr&gt;</span>
2021
+ <span class="nt">&lt;/Admin&gt;</span>
2022
+
2023
+ <span class="c">&lt;!-- Both of these transports use the Kerberos</span>
2024
+ <span class="c"> configuration above for authentication. --&gt;</span>
2025
+ <span class="nt">&lt;Transports&gt;</span>
2026
+ <span class="nt">&lt;Transport&gt;</span>
2027
+ <span class="nt">&lt;Name&gt;</span>json-tcp<span class="nt">&lt;/Name&gt;</span>
2028
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
2029
+ <span class="nt">&lt;InetAddr&gt;</span>9007<span class="nt">&lt;/InetAddr&gt;</span>
2030
+ <span class="nt">&lt;MessageType&gt;</span>json<span class="nt">&lt;/MessageType&gt;</span>
2031
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
2032
+ <span class="nt">&lt;/Transport&gt;</span>
2033
+ <span class="nt">&lt;Transport&gt;</span>
2034
+ <span class="nt">&lt;Name&gt;</span>any-tcp<span class="nt">&lt;/Name&gt;</span>
2035
+ <span class="nt">&lt;Type&gt;</span>tcp<span class="nt">&lt;/Type&gt;</span>
2036
+ <span class="nt">&lt;InetAddr&gt;</span>9090<span class="nt">&lt;/InetAddr&gt;</span>
2037
+ <span class="nt">&lt;Protocol&gt;</span>amps<span class="nt">&lt;/Protocol&gt;</span>
2038
+ <span class="nt">&lt;/Transport&gt;</span>
2039
+ <span class="nt">&lt;/Transports&gt;</span>
2040
+
2041
+ <span class="c">&lt;!-- other configuration here --&gt;</span>
2042
+
2043
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
2044
+ </pre></div>
2045
+ </div>
2046
+ </div>
2047
+ </div>
2048
+ <div class="section" id="entitlement-with-the-simple-access-module">
2049
+ <span id="ug-simple-access"></span><h2>Entitlement with the Simple Access Module<a class="headerlink" href="#entitlement-with-the-simple-access-module" title="Permalink to this headline">¶</a></h2>
2050
+ <p>The AMPS distribution includes a module that provides access to
2051
+ resources that meet specific patterns. In this release, the simple
2052
+ access entitlement module is provided with AMPS, but is not loaded by
2053
+ default. This module is an optional extension to the AMPS product, and
2054
+ while it is included with the AMPS distribution, the module must be
2055
+ explicitly loaded, enabled, and configured.</p>
2056
+ <p>When using this module, AMPS grants and denies permissions to resources
2057
+ based on the name of the resource. The name of the user is not
2058
+ considered by this module, so when this module is used every user has
2059
+ the same set of permissions for the transport.</p>
2060
+ <div class="section" id="when-to-use-the-simple-access-module">
2061
+ <h3>When to Use the Simple Access Module<a class="headerlink" href="#when-to-use-the-simple-access-module" title="Permalink to this headline">¶</a></h3>
2062
+ <p>The AMPS Simple Access module can be a good option when:</p>
2063
+ <ul class="simple">
2064
+ <li>There are specific topics for a transport that are allowed or denied,
2065
+ but no other restrictions on the transport.</li>
2066
+ <li>There is no other entitlement system in use for the installation.</li>
2067
+ </ul>
2068
+ <p>Most often, the simple access module is used to allow access to the
2069
+ parts of the Admin console that do not modify the state of an AMPS
2070
+ instance, while refusing access to the parts of the Admin console that
2071
+ affect the instance state.</p>
2072
+ </div>
2073
+ <div class="section" id="configuring-amps-to-use-the-simple-access-module">
2074
+ <h3>Configuring AMPS to use the Simple Access Module<a class="headerlink" href="#configuring-amps-to-use-the-simple-access-module" title="Permalink to this headline">¶</a></h3>
2075
+ <p>The simple access entitlement module is included in the AMPS
2076
+ distribution, but is not loaded in AMPS by default. To load the module,
2077
+ add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code> block in your AMPS
2078
+ configuration:</p>
2079
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
2080
+ ...
2081
+
2082
+ <span class="nt">&lt;Module&gt;</span>
2083
+ <span class="nt">&lt;Name&gt;</span>simple-access<span class="nt">&lt;/Name&gt;</span>
2084
+ <span class="nt">&lt;Library&gt;</span>libamps_simple_access_entitlement.so<span class="nt">&lt;/Library&gt;</span>
2085
+
2086
+ <span class="c">&lt;!-- This module does not require options when loaded. --&gt;</span>
2087
+ <span class="nt">&lt;/Module&gt;</span>
2088
+
2089
+ ...
2090
+ <span class="nt">&lt;/Modules&gt;</span>
2091
+ </pre></div>
2092
+ </div>
2093
+ <p>Options for the module are set when the module is used for <code class="docutils literal"><span class="pre">Entitlement</span></code>.
2094
+ When used in an <code class="docutils literal"><span class="pre">Entitlement</span></code> block, the module requires the <code class="docutils literal"><span class="pre">AllowedTopics</span></code>
2095
+ and/or <code class="docutils literal"><span class="pre">DeniedTopics</span></code> options to be specified.</p>
2096
+ <table border="1" class="docutils" id="id19">
2097
+ <caption><span class="caption-text"><em>Entitlement block options for Simple Access Entitlement Module</em></span><a class="headerlink" href="#id19" title="Permalink to this table">¶</a></caption>
2098
+ <colgroup>
2099
+ <col width="50%" />
2100
+ <col width="50%" />
2101
+ </colgroup>
2102
+ <thead valign="bottom">
2103
+ <tr class="row-odd"><th class="head">Option</th>
2104
+ <th class="head">Description</th>
2105
+ </tr>
2106
+ </thead>
2107
+ <tbody valign="top">
2108
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">AllowedTopics</span></code></td>
2109
+ <td><p class="first">A regular expression that matches
2110
+ the topics that the module will
2111
+ allow access to. The module will
2112
+ grant access only to topics that
2113
+ match this regular expression and
2114
+ do not match the <code class="docutils literal"><span class="pre">DeniedTopics</span></code>
2115
+ regular expression.</p>
2116
+ <p class="last">Defaults to <code class="docutils literal"><span class="pre">.*</span></code>, matching all
2117
+ topics in the instance.</p>
2118
+ </td>
2119
+ </tr>
2120
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">DeniedTopics</span></code></td>
2121
+ <td><p class="first">A regular expression that matches
2122
+ the topics that the module will deny
2123
+ access to. The module will grant
2124
+ access only to topics that do not
2125
+ match this regular expression.</p>
2126
+ <p class="last">There is no default for this
2127
+ parameter. If not provided, the
2128
+ module does not consider any topics
2129
+ to be explicitly denied and will
2130
+ grant access to any topic that
2131
+ matches the <code class="docutils literal"><span class="pre">AllowedTopics</span></code>
2132
+ parameter.</p>
2133
+ </td>
2134
+ </tr>
2135
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">GrantedPermissions</span></code></td>
2136
+ <td><p class="first">When set, this option directs the
2137
+ module to grant only read or write
2138
+ permissions when a topic is allowed.</p>
2139
+ <p>This option accepts a value of
2140
+ <code class="docutils literal"><span class="pre">read</span></code> or <code class="docutils literal"><span class="pre">write</span></code>, specifying
2141
+ which permission the module will
2142
+ grant.</p>
2143
+ <p>There is no default for this
2144
+ parameter. If not provided, the
2145
+ module will grant both read and
2146
+ write permissions to any allowed
2147
+ topic.</p>
2148
+ <div class="last admonition tip">
2149
+ <p class="first admonition-title">Tip</p>
2150
+ <p class="last">When using this option for
2151
+ the <code class="docutils literal"><span class="pre">Admin</span></code> transport, notice
2152
+ that the <code class="docutils literal"><span class="pre">administrator</span></code>
2153
+ actions use an HTTP <code class="docutils literal"><span class="pre">GET</span></code>,
2154
+ so they are considered read
2155
+ operations.</p>
2156
+ </div>
2157
+ </td>
2158
+ </tr>
2159
+ </tbody>
2160
+ </table>
2161
+ <p>For example, the following configuration loads the module, uses the
2162
+ module for entitlements on the administrative console, and explicitly
2163
+ refuses access to paths beneath <code class="docutils literal"><span class="pre">/amps/administrator</span></code> &#8211; the paths
2164
+ that might modify the state of the instance. Since <code class="docutils literal"><span class="pre">AllowedTopics</span></code>
2165
+ defaults to <code class="docutils literal"><span class="pre">.*</span></code>, all other topics are allowed.</p>
2166
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
2167
+
2168
+ <span class="nt">&lt;Modules&gt;</span>
2169
+ ...
2170
+
2171
+ <span class="nt">&lt;Module&gt;</span>
2172
+ <span class="nt">&lt;Name&gt;</span>simple-access<span class="nt">&lt;/Name&gt;</span>
2173
+ <span class="nt">&lt;Library&gt;</span>libamps_simple_access_entitlement.so<span class="nt">&lt;/Library&gt;</span>
2174
+ <span class="nt">&lt;/Module&gt;</span>
2175
+
2176
+ ...
2177
+ <span class="nt">&lt;/Modules&gt;</span>
2178
+
2179
+
2180
+ <span class="nt">&lt;Admin&gt;</span>
2181
+ <span class="nt">&lt;InetAddr&gt;</span>localhost:8085<span class="nt">&lt;/InetAddr&gt;</span>
2182
+ <span class="c">&lt;!-- Use the simple-access module to deny access to topics under</span>
2183
+ <span class="c"> /amps/administrator. --&gt;</span>
2184
+ <span class="nt">&lt;Entitlement&gt;</span>
2185
+ <span class="nt">&lt;Module&gt;</span>simple-access<span class="nt">&lt;/Module&gt;</span>
2186
+ <span class="nt">&lt;Options&gt;</span>
2187
+ <span class="c">&lt;!-- Deny all topics under /amps/administrator --&gt;</span>
2188
+ <span class="nt">&lt;DeniedTopics&gt;</span>^/amps/administrator<span class="nt">&lt;/DeniedTopics&gt;</span>
2189
+
2190
+ <span class="c">&lt;!-- Allowed topics defaults to .* , so no need</span>
2191
+ <span class="c"> to set that explicitly. --&gt;</span>
2192
+ <span class="nt">&lt;/Options&gt;</span>
2193
+ <span class="nt">&lt;/Entitlement&gt;</span>
2194
+ <span class="nt">&lt;/Admin&gt;</span>
2195
+
2196
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
2197
+ </pre></div>
2198
+ </div>
2199
+ </div>
2200
+ </div>
2201
+ <div class="section" id="providing-replication-credentials-with-the-amps-multimechanism-authenticator-module">
2202
+ <span id="ug-multimechanism-authenticator"></span><span id="ug-multi-authenticator"></span><h2>Providing Replication Credentials with the AMPS Multimechanism Authenticator Module<a class="headerlink" href="#providing-replication-credentials-with-the-amps-multimechanism-authenticator-module" title="Permalink to this headline">¶</a></h2>
2203
+ <p>AMPS includes a module that can provide credentials for outgoing replication
2204
+ connections, that is designed for use when the multimechanism authenticator module
2205
+ is in use for the destination AMPS instance.</p>
2206
+ <p>In this release, this module can provide credentials for both LDAP and
2207
+ Kerberos authenticator mechanisms. This module is provided with AMPS,
2208
+ but it is not loaded by default. This module is an optional extension to
2209
+ the AMPS product and while it is included with the AMPS distribution,
2210
+ the module must be explicitly loaded, enabled, and configured.</p>
2211
+ <div class="section" id="when-to-use-the-multimechanism-authenticator-module">
2212
+ <h3>When to Use the Multimechanism Authenticator Module<a class="headerlink" href="#when-to-use-the-multimechanism-authenticator-module" title="Permalink to this headline">¶</a></h3>
2213
+ <p>60East recommends using this module when a replication connection is
2214
+ authenticated and uses the AMPS multimechanism module with Kerberos
2215
+ configured. This module can also be useful when LDAP is configured,
2216
+ however, in many environments the password capabilities of the
2217
+ <code class="docutils literal"><span class="pre">amps-default-authenticator</span></code> module can be sufficient for LDAP
2218
+ authentication.</p>
2219
+ </div>
2220
+ <div class="section" id="id2">
2221
+ <h3>Setting Authentication Mechanisms<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
2222
+ <p>To enable a particular authentication mechanism in the
2223
+ multimechanism authenticator module, you simply provide
2224
+ configuration parameters for that mechanism.</p>
2225
+ <p>For example, if you provide configuration parameters for an
2226
+ LDAP server, the module will enable LDAP. If you provide
2227
+ configuration parameters for Kerberos, the module will enable
2228
+ Kerberos.</p>
2229
+ </div>
2230
+ <div class="section" id="configuring-amps-to-use-the-multimechanism-authenticator-module">
2231
+ <h3>Configuring AMPS to use the Multimechanism Authenticator Module<a class="headerlink" href="#configuring-amps-to-use-the-multimechanism-authenticator-module" title="Permalink to this headline">¶</a></h3>
2232
+ <p>The multimechanism authenticator module is included in the AMPS
2233
+ distribution, but is not loaded in AMPS by default. To load the
2234
+ module, add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code>
2235
+ block in your AMPS configuration:</p>
2236
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
2237
+ ...
2238
+
2239
+ <span class="nt">&lt;Module&gt;</span>
2240
+ <span class="nt">&lt;Name&gt;</span>multimech-authenticator<span class="nt">&lt;/Name&gt;</span>
2241
+ <span class="nt">&lt;Library&gt;</span>libamps_multi_authenticator.so<span class="nt">&lt;/Library&gt;</span>
2242
+ <span class="nt">&lt;/Module&gt;</span>
2243
+
2244
+ ...
2245
+ <span class="nt">&lt;/Modules&gt;</span>
2246
+ </pre></div>
2247
+ </div>
2248
+ <p>This module does not require any options as a part of the module configuration
2249
+ and ignores any options provided when the module is loaded.</p>
2250
+ <p>This module supports the following options when used in an <code class="docutils literal"><span class="pre">Authenticator</span></code>
2251
+ block:</p>
2252
+ <p><strong>Kerberos Options</strong></p>
2253
+ <table border="1" class="docutils">
2254
+ <colgroup>
2255
+ <col width="40%" />
2256
+ <col width="60%" />
2257
+ </colgroup>
2258
+ <thead valign="bottom">
2259
+ <tr class="row-odd"><th class="head">Option</th>
2260
+ <th class="head">Description</th>
2261
+ </tr>
2262
+ </thead>
2263
+ <tbody valign="top">
2264
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Kerberos.Keytab</span></code></td>
2265
+ <td><p class="first">Sets a keytab file to use for Kerberos authentication.
2266
+ This option must be set to the path of the file, which
2267
+ can be either an absolute path or a relative path
2268
+ based on the current working directory of the AMPS
2269
+ server process.</p>
2270
+ <p>When this option is specified, the module will provide
2271
+ Kerberos authentication and a <code class="docutils literal"><span class="pre">Kerberos.SPN</span></code> must
2272
+ be specified.</p>
2273
+ <p class="last">There is no default for this parameter.</p>
2274
+ </td>
2275
+ </tr>
2276
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">Kerberos.SPN</span></code></td>
2277
+ <td><p class="first">Sets the Service Principal Name (SPN) to use for
2278
+ Kerberos authentication.</p>
2279
+ <p>When this option is specified, the module will provide
2280
+ Kerberos authentication and a <code class="docutils literal"><span class="pre">Kerberos.Keytab</span></code> must
2281
+ be specified.</p>
2282
+ <p class="last">There is no default for this parameter.</p>
2283
+ </td>
2284
+ </tr>
2285
+ </tbody>
2286
+ </table>
2287
+ <p><em>Kerberos options for the Multimechanism Authenticator</em></p>
2288
+ <p><strong>LDAP Options</strong></p>
2289
+ <table border="1" class="docutils">
2290
+ <colgroup>
2291
+ <col width="40%" />
2292
+ <col width="60%" />
2293
+ </colgroup>
2294
+ <thead valign="bottom">
2295
+ <tr class="row-odd"><th class="head">Option</th>
2296
+ <th class="head">Description</th>
2297
+ </tr>
2298
+ </thead>
2299
+ <tbody valign="top">
2300
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">LDAP.Username</span></code></td>
2301
+ <td><p class="first">Sets the username to provide when authenticating to
2302
+ a destination that uses LDAP authentication.</p>
2303
+ <p>When this option is specified, the module will
2304
+ provide LDAP authentication. This parameter is
2305
+ required if the <code class="docutils literal"><span class="pre">LDAP.PasswordFile</span></code> parameter is
2306
+ specified.</p>
2307
+ <p class="last">There is no default for this parameter.</p>
2308
+ </td>
2309
+ </tr>
2310
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">LDAP.PasswordFile</span></code></td>
2311
+ <td><p class="first">Specifies the file name from which to read the
2312
+ password to provide when authenticating to a
2313
+ destination that uses LDAP authentication.</p>
2314
+ <p>When this option is specified, the module will
2315
+ provide LDAP authentication and an <code class="docutils literal"><span class="pre">LDAP.Username</span></code>
2316
+ must also be specified.</p>
2317
+ <p class="last">There is no default for this parameter.</p>
2318
+ </td>
2319
+ </tr>
2320
+ </tbody>
2321
+ </table>
2322
+ <p><em>LDAP options for the Multimechanism Authenticator</em></p>
2323
+ <p>The module must be configured with at least one method for providing credentials. Otherwise, the module fails to initialize and AMPS will halt the startup process.</p>
2324
+ <p>For example, the following configuration loads the module and configures
2325
+ the module to provide Kerberos tokens to the destination at <code class="docutils literal"><span class="pre">my-failover-partner:4000</span></code>.</p>
2326
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
2327
+
2328
+ <span class="nt">&lt;Modules&gt;</span>
2329
+ ...
2330
+
2331
+ <span class="nt">&lt;Module&gt;</span>
2332
+ <span class="nt">&lt;Name&gt;</span>multi-authenticator<span class="nt">&lt;/Name&gt;</span>
2333
+ <span class="nt">&lt;Library&gt;</span>libamps_multi_authenticator.so<span class="nt">&lt;/Library&gt;</span>
2334
+ <span class="nt">&lt;/Module&gt;</span>
2335
+
2336
+ ...
2337
+ <span class="nt">&lt;/Modules&gt;</span>
2338
+
2339
+ ...
2340
+
2341
+ <span class="nt">&lt;Replication&gt;</span>
2342
+
2343
+ ...
2344
+
2345
+ <span class="nt">&lt;Destination&gt;</span>
2346
+ <span class="nt">&lt;Transport&gt;</span>
2347
+
2348
+ <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
2349
+ <span class="nt">&lt;InetAddr&gt;</span>my-failover-partner:4000<span class="nt">&lt;/InetAddr&gt;</span>
2350
+
2351
+ <span class="nt">&lt;Authenticator&gt;</span>
2352
+ <span class="nt">&lt;Module&gt;</span>multi-authenticator<span class="nt">&lt;/Module&gt;</span>
2353
+ <span class="nt">&lt;Options&gt;</span>
2354
+ <span class="nt">&lt;Kerberos.SPN&gt;</span>AMPS/host.domain.com<span class="nt">&lt;/Kerberos.SPN&gt;</span>
2355
+ <span class="nt">&lt;Kerberos.Keytab&gt;</span>/path/to/amps.keytab<span class="nt">&lt;/Kerberos.Keytab&gt;</span>
2356
+ <span class="nt">&lt;/Options&gt;</span>
2357
+ <span class="nt">&lt;/Authenticator&gt;</span>
2358
+
2359
+ <span class="nt">&lt;/Transport&gt;</span>
2360
+ <span class="nt">&lt;/Destination&gt;</span>
2361
+
2362
+ <span class="nt">&lt;/Replication&gt;</span>
2363
+
2364
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
2365
+ </pre></div>
2366
+ </div>
2367
+ </div>
2368
+ </div>
2369
+ <div class="section" id="providing-replication-credentials-with-the-amps-exec-authenticator-module">
2370
+ <span id="ug-exec-authenticator-using"></span><span id="ug-exec-authenticator"></span><h2>Providing Replication Credentials with the AMPS Exec Authenticator Module<a class="headerlink" href="#providing-replication-credentials-with-the-amps-exec-authenticator-module" title="Permalink to this headline">¶</a></h2>
2371
+ <p>AMPS includes a module that can provide credentials for outgoing replication
2372
+ connections using the results of an external process. This is designed
2373
+ for cases where a site has an authentication system that requires
2374
+ short-lived tokens, and where the installation does not use
2375
+ Kerberos, so the multimechanism authentication module cannot be used.</p>
2376
+ <p>In this release, the exec authenticator module is provided with AMPS,
2377
+ but is not loaded by default. This module is an optional extension to
2378
+ the AMPS product, and while it is included with the AMPS distribution,
2379
+ the module must be explicitly loaded, enabled, and configured.</p>
2380
+ <div class="admonition tip">
2381
+ <p class="first admonition-title">Tip</p>
2382
+ <p class="last">This module runs an external application with the
2383
+ credentials of the AMPS server itself. Avoid using
2384
+ this module unless you fully trust the application,
2385
+ have verified that the command line provided is
2386
+ correct and cannot use another module (or a
2387
+ custom module) for authentication.</p>
2388
+ </div>
2389
+ <div class="section" id="when-to-use-the-exec-authenticator-module">
2390
+ <h3>When to Use the Exec Authenticator Module<a class="headerlink" href="#when-to-use-the-exec-authenticator-module" title="Permalink to this headline">¶</a></h3>
2391
+ <p>60East recommends using this module when a replication connection is
2392
+ authenticated, when a system other than Kerberos is in use,
2393
+ when the credentials to be used cannot be provided in the
2394
+ configuration file or stored in the filesystem and when
2395
+ an executable program or script is available that can
2396
+ produce the credentials to use for a replication connection.</p>
2397
+ <ul class="simple">
2398
+ <li>If the credentials can be provided in the configuration file
2399
+ or stored in a file in the file system, use the
2400
+ <code class="docutils literal"><span class="pre">amps-default-authenticator-module</span></code>.</li>
2401
+ <li>If Kerberos is in use, use the <a class="reference internal" href="#ug-multi-authenticator"><span class="std std-ref">AMPS Multimechanism Authenticator Module</span></a>.</li>
2402
+ </ul>
2403
+ </div>
2404
+ <div class="section" id="configuring-amps-to-use-the-exec-authenticator-module">
2405
+ <h3>Configuring AMPS to use the Exec Authenticator Module<a class="headerlink" href="#configuring-amps-to-use-the-exec-authenticator-module" title="Permalink to this headline">¶</a></h3>
2406
+ <p>The exec authenticator module is included in the AMPS
2407
+ distribution, but is not loaded in AMPS by default. To load the
2408
+ module, add the following configuration item to the <code class="docutils literal"><span class="pre">Modules</span></code>
2409
+ block in your AMPS configuration:</p>
2410
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Modules&gt;</span>
2411
+ ...
2412
+
2413
+ <span class="nt">&lt;Module&gt;</span>
2414
+ <span class="nt">&lt;Name&gt;</span>exec-authenticator<span class="nt">&lt;/Name&gt;</span>
2415
+ <span class="nt">&lt;Library&gt;</span>libamps_exec_authenticator.so<span class="nt">&lt;/Library&gt;</span>
2416
+ <span class="nt">&lt;/Module&gt;</span>
2417
+
2418
+ ...
2419
+ <span class="nt">&lt;/Modules&gt;</span>
2420
+ </pre></div>
2421
+ </div>
2422
+ <p>This module does not require any options as a part of the module configuration
2423
+ and ignores any options provided when the module is loaded.</p>
2424
+ <p>This module supports the following options when used in an <code class="docutils literal"><span class="pre">Authenticator</span></code>
2425
+ block:</p>
2426
+ <table border="1" class="docutils" id="id20">
2427
+ <caption><span class="caption-text"><em>Options for the Exec Authenticator</em></span><a class="headerlink" href="#id20" title="Permalink to this table">¶</a></caption>
2428
+ <colgroup>
2429
+ <col width="50%" />
2430
+ <col width="50%" />
2431
+ </colgroup>
2432
+ <thead valign="bottom">
2433
+ <tr class="row-odd"><th class="head">Option</th>
2434
+ <th class="head">Description</th>
2435
+ </tr>
2436
+ </thead>
2437
+ <tbody valign="top">
2438
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">Command</span></code></td>
2439
+ <td><p class="first">Sets the command to run.</p>
2440
+ <p>This can be either an absolute path or a relative
2441
+ path based on the current working directory of the
2442
+ AMPS server process.</p>
2443
+ <p>The command supports the following expansions
2444
+ when the command runs:</p>
2445
+ <ul>
2446
+ <li><p class="first"><code class="docutils literal"><span class="pre">AMPS_USER_NAME</span></code> The user name that the
2447
+ authenticator will provide to the remote server.</p>
2448
+ <p>For example, the following <code class="docutils literal"><span class="pre">Command</span></code> runs the
2449
+ script <code class="docutils literal"><span class="pre">give_me_a_token.sh</span></code> from the path
2450
+ <code class="docutils literal"><span class="pre">/opt/site/gateways/</span></code>, passing the user name
2451
+ as a parameter:</p>
2452
+ <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Command</span><span class="o">&gt;/</span><span class="n">opt</span><span class="o">/</span><span class="n">site</span><span class="o">/</span><span class="n">gateways</span><span class="o">/</span><span class="n">give_me_a_token</span><span class="o">.</span><span class="n">sh</span>
2453
+ <span class="s2">&quot;{{AMPS_USER_NAME}}&quot;</span><span class="o">&lt;/</span><span class="n">Command</span><span class="o">&gt;</span>
2454
+ </pre></div>
2455
+ </div>
2456
+ </li>
2457
+ </ul>
2458
+ <p>The authenticator will read the stdout of that
2459
+ command and provide the result as the authentication
2460
+ token for the connection.</p>
2461
+ <p class="last">There is no default for this parameter.</p>
2462
+ </td>
2463
+ </tr>
2464
+ <tr class="row-odd"><td><code class="docutils literal"><span class="pre">MaxLength</span></code></td>
2465
+ <td><p class="first">Sets the maximum number of bytes to read from the
2466
+ command.</p>
2467
+ <p class="last">Default: <code class="docutils literal"><span class="pre">1024</span></code></p>
2468
+ </td>
2469
+ </tr>
2470
+ <tr class="row-even"><td><code class="docutils literal"><span class="pre">UserName</span></code></td>
2471
+ <td><p class="first">Sets the user name to provide on this connection.</p>
2472
+ <p class="last">There is no default for this parameter.</p>
2473
+ </td>
2474
+ </tr>
2475
+ </tbody>
2476
+ </table>
2477
+ <p>The module must be configured with a <code class="docutils literal"><span class="pre">Command</span></code> and <code class="docutils literal"><span class="pre">UserName</span></code>. Otherwise,
2478
+ the module fails to initialize and AMPS will halt the startup process.</p>
2479
+ <p>For example, the following configuration loads and configures the module to
2480
+ run the <code class="docutils literal"><span class="pre">auth-widget</span></code> program, in the current working directory of the AMPS process,
2481
+ in order to provide credentials. The UserName provided to AMPS, as well as on the
2482
+ command line for <code class="docutils literal"><span class="pre">auth-widget</span></code>, is sourced from the <code class="docutils literal"><span class="pre">USER</span></code> environment variable used
2483
+ during AMPS startup. The options provided on the <code class="docutils literal"><span class="pre">auth-widget</span></code> command line are needed
2484
+ for the program to generate the token and write it to standard output.</p>
2485
+ <div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;AMPSConfig&gt;</span>
2486
+
2487
+ <span class="nt">&lt;Modules&gt;</span>
2488
+ ...
2489
+
2490
+ <span class="nt">&lt;Module&gt;</span>
2491
+ <span class="nt">&lt;Name&gt;</span>run-proc-authenticator<span class="nt">&lt;/Name&gt;</span>
2492
+ <span class="nt">&lt;Library&gt;</span>libamps_exec_authenticator.so<span class="nt">&lt;/Library&gt;</span>
2493
+ <span class="nt">&lt;/Module&gt;</span>
2494
+
2495
+ ...
2496
+ <span class="nt">&lt;/Modules&gt;</span>
2497
+
2498
+ ...
2499
+
2500
+ <span class="nt">&lt;Replication&gt;</span>
2501
+
2502
+ ...
2503
+
2504
+ <span class="nt">&lt;Destination&gt;</span>
2505
+ <span class="nt">&lt;Transport&gt;</span>
2506
+
2507
+ <span class="nt">&lt;Type&gt;</span>amps-replication<span class="nt">&lt;/Type&gt;</span>
2508
+ <span class="nt">&lt;InetAddr&gt;</span>my-failover-partner:4000<span class="nt">&lt;/InetAddr&gt;</span>
2509
+
2510
+ <span class="nt">&lt;Authenticator&gt;</span>
2511
+ <span class="nt">&lt;Module&gt;</span>run-proc-authenticator<span class="nt">&lt;/Module&gt;</span>
2512
+ <span class="nt">&lt;Options&gt;</span>
2513
+ <span class="nt">&lt;UserName&gt;</span>${USER}<span class="nt">&lt;/UserName&gt;</span>
2514
+ <span class="nt">&lt;Command&gt;</span>./auth-widget --user &quot;{{AMPS_USER_NAME}}&quot; --output=stdout<span class="nt">&lt;/Command&gt;</span>
2515
+ <span class="nt">&lt;/Options&gt;</span>
2516
+ <span class="nt">&lt;/Authenticator&gt;</span>
2517
+
2518
+ <span class="nt">&lt;/Transport&gt;</span>
2519
+ <span class="nt">&lt;/Destination&gt;</span>
2520
+ <span class="nt">&lt;/Replication&gt;</span>
2521
+
2522
+ <span class="nt">&lt;/AMPSConfig&gt;</span>
2523
+ </pre></div>
2524
+ </div>
2525
+ </div>
2526
+ </div>
2527
+ </div>
2528
+
2529
+
2530
+ </div>
2531
+ </div>
2532
+ </div>
2533
+ <div class="clearer"></div>
2534
+ </div>
2535
+ <div class="footer">
2536
+ &copy;2023 60East Technologies, Inc. (version develop).
2537
+
2538
+ |
2539
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
2540
+ &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
2541
+
2542
+ </div>
2543
+
2544
+
2545
+
2546
+
2547
+ </body>
2548
+ </html>