27/Admin_Guide.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.17">
<meta name="author" content="WildFly developer team">
<title>WildFly Admin Guide</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
pre.CodeRay{background:#f7f7f8}
.CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
.CodeRay .line-numbers strong{color:#000}
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.CodeRay td{vertical-align:top;line-height:inherit}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.code{padding:0 0 0 .75em}
.CodeRay .debug{color:#fff!important;background:navy!important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:navy}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:teal}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:teal}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:teal}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body id="Admin_Guide" class="book toc2 toc-left">
<div id="header">
<h1>WildFly Admin Guide</h1>
<div class="details">
<span id="author" class="author">WildFly developer team</span><br>
<span id="revnumber">version 27.0.0.Final,</span>
<span id="revdate">2022-11-08T01:15:58Z</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">WildFly Admin guide</div>
<ul class="sectlevel1">
<li><a href="#Target_Audience">1. Target Audience</a>
<ul class="sectlevel2">
<li><a href="#prerequisites">1.1. Prerequisites</a></li>
<li><a href="#examples-in-this-guide">1.2. Examples in this guide</a></li>
</ul>
</li>
<li><a href="#Core_management_concepts">2. Core management concepts</a>
<ul class="sectlevel2">
<li><a href="#Operating_modes">2.1. Operating mode</a></li>
<li><a href="#General_configuration_concepts">2.2. General configuration concepts</a></li>
<li><a href="#management-resources">2.3. Management resources</a></li>
</ul>
</li>
<li><a href="#Management_Clients">3. Management Clients</a>
<ul class="sectlevel2">
<li><a href="#web-management-interface">3.1. Web Management Interface</a></li>
<li><a href="#Command_Line_Interface">3.2. Command Line Interface</a></li>
<li><a href="#Default_HTTP_Interface_Security">3.3. Default HTTP Interface Security</a></li>
<li><a href="#Default_Native_Interface_Security">3.4. Default Native Interface Security</a></li>
<li><a href="#command-line-interface">3.5. Command Line Interface</a></li>
<li><a href="#configuration-files">3.6. Configuration Files</a></li>
</ul>
</li>
<li><a href="#Interfaces_and_ports">4. Interfaces and ports</a>
<ul class="sectlevel2">
<li><a href="#interface-declarations">4.1. Interface declarations</a></li>
<li><a href="#socket-binding-groups">4.2. Socket Binding Groups</a></li>
<li><a href="#ipv4-versus-ipv6">4.3. IPv4 versus IPv6</a></li>
</ul>
</li>
<li><a href="#administrative-security">5. Administrative security</a>
<ul class="sectlevel2">
<li><a href="#add-user-utility">5.1. add-user utility</a></li>
<li><a href="#RBAC">5.2. Authorizing management actions with Role Based Access Control</a></li>
</ul>
</li>
<li><a href="#application-deployment">6. Application deployment</a>
<ul class="sectlevel2">
<li><a href="#managed-domain-3">6.1. Managed Domain</a></li>
<li><a href="#standalone-server-3">6.2. Standalone Server</a></li>
<li><a href="#managed-and-unmanaged-deployments">6.3. Managed and Unmanaged Deployments</a></li>
<li><a href="#Deployment_Overlays">6.4. Deployment Overlays</a></li>
</ul>
</li>
<li><a href="#Subsystem_configuration">7. Subsystem configuration</a>
<ul class="sectlevel2">
<li><a href="#EE">7.1. EE Subsystem Configuration</a></li>
<li><a href="#Naming">7.2. Naming Subsystem Configuration</a></li>
<li><a href="#DataSource">7.3. DataSource configuration</a></li>
<li><a href="#agroal">7.4. Agroal configuration</a></li>
<li><a href="#Logging">7.5. Logging Configuration</a></li>
<li><a href="#EJB3">7.6. EJB3 subsystem configuration guide</a></li>
<li><a href="#Undertow">7.7. Undertow subsystem configuration</a></li>
<li><a href="#Messaging">7.8. Messaging configuration</a></li>
<li><a href="#Transactions_Subsystem">7.9. Transactions subsystem configuration</a></li>
<li><a href="#MicroProfile_Metrics_SmallRye">7.10. Metrics Subsystem Configuration</a></li>
<li><a href="#Micrometer_Metrics">7.11. Micrometer Metrics Subsystem (Preview) Configuration</a></li>
<li><a href="#Observability_Tracing">7.12. OpenTelemetry Subsystem Configuration</a></li>
<li><a href="#Health">7.13. Health Subsystem Configuration</a></li>
<li><a href="#MicroProfile_Config_SmallRye">7.14. MicroProfile Config Subsystem Configuration</a></li>
<li><a href="#MicroProfile_Health_SmallRye">7.15. MicroProfile Health Subsystem Configuration</a></li>
<li><a href="#MicroProfile_JWT_SmallRye">7.16. MicroProfile JWT Subsystem Configuration</a></li>
<li><a href="#MicroProfile_Metrics_SmallRye_Subsystem_Config">7.17. MicroProfile Metrics Subsystem Configuration</a></li>
<li><a href="#MicroProfile_OpenAPI_SmallRye">7.18. MicroProfile OpenAPI Subsystem Configuration</a></li>
<li><a href="#MicroProfile_OpenTracing_SmallRye">7.19. MicroProfile OpenTracing Subsystem Configuration</a></li>
<li><a href="#MicroProfile-Fault-Tolerance-SmallRye">7.20. MicroProfile Fault Tolerance Subsystem</a></li>
<li><a href="#MicroProfile_Reactive_Streams_Operators_SmallRye">7.21. MicroProfile Reactive Streams Operators Subsystem Configuration</a></li>
<li><a href="#MicroProfile_Reactive_Messaging_SmallRye">7.22. MicroProfile Reactive Messaging Subsystem Configuration</a></li>
<li><a href="#Web_services">7.23. Web services configuration</a></li>
<li><a href="#Resource_adapters">7.24. Resource adapters</a></li>
<li><a href="#Jakarta_Batch">7.25. Jakarta Batch Subsystem Configuration</a></li>
<li><a href="#Jakarta_Server_Faces">7.26. Jakarta Server Faces Configuration</a></li>
<li><a href="#JMX">7.27. JMX subsystem configuration</a></li>
<li><a href="#Deployment_Scanner">7.28. Deployment Scanner configuration</a></li>
<li><a href="#Core_Management">7.29. Core Management Subsystem Configuration</a></li>
<li><a href="#Elytron_OIDC_Client">7.30. Elytron OpenID Connect Client Subsystem Configuration</a></li>
<li><a href="#Simple_configuration_subsystems">7.31. Simple configuration subsystems</a></li>
</ul>
</li>
<li><a href="#Domain_Setup">8. Domain Setup</a>
<ul class="sectlevel2">
<li><a href="#domain-controller-configuration">8.1. Domain Controller Configuration</a></li>
<li><a href="#host-controller-configuration">8.2. Host Controller Configuration</a></li>
<li><a href="#server-groups">8.3. Server groups</a></li>
<li><a href="#servers">8.4. Servers</a></li>
</ul>
</li>
<li><a href="#Management_tasks">9. Management tasks</a>
<ul class="sectlevel2">
<li><a href="#Command_line_parameters">9.1. Command line parameters</a></li>
<li><a href="#Suspend">9.2. Suspend, Resume and Graceful shutdown</a></li>
<li><a href="#Starting_and_Stopping_Servers_in_a_Managed_Domain">9.3. Starting and Stopping Servers in a Managed Domain</a></li>
<li><a href="#JVM_settings">9.4. JVM settings</a></li>
<li><a href="#Audit_logging">9.5. Audit logging</a></li>
<li><a href="#Canceling_Management_Operations">9.6. Canceling Management Operations</a></li>
<li><a href="#Configuration_file_history">9.7. Configuration file history</a></li>
<li><a href="#Configuration_file_git_history">9.8. Git Configuration file history</a></li>
<li><a href="#YAML_Configuration_file">9.9. (YAML) Configuration file (Experimental))</a></li>
</ul>
</li>
<li><a href="#Management_API_reference">10. Management API reference</a>
<ul class="sectlevel2">
<li><a href="#Global_operations">10.1. Global operations</a></li>
<li><a href="#Detyped_management_and_the_jboss-dmr_library">10.2. Detyped management and the jboss-dmr library</a></li>
<li><a href="#Description_of_the_Management_Model">10.3. Description of the Management Model</a></li>
<li><a href="#The_HTTP_management_API">10.4. The HTTP management API</a></li>
<li><a href="#The_native_management_API">10.5. The native management API</a></li>
</ul>
</li>
<li><a href="#CLI_Recipes">11. CLI Recipes</a>
<ul class="sectlevel2">
<li><a href="#properties">11.1. Properties</a></li>
<li><a href="#configuration-9">11.2. Configuration</a></li>
<li><a href="#runtime">11.3. Runtime</a></li>
<li><a href="#scripting">11.4. Scripting</a></li>
<li><a href="#statistics">11.5. Statistics</a></li>
<li><a href="#cli_deployment">11.6. Deployment</a></li>
<li><a href="#downloading-files-with-the-cli">11.7. Downloading files with the CLI</a></li>
<li><a href="#iteration-of-collections">11.8. Iteration of Collections</a></li>
<li><a href="#cli-security-commands">11.9. Security Commands</a></li>
<li><a href="#mp-cli-script">11.10. Evolving standard configurations with support for MicroProfile</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>&#169; 2017 The original authors.</p>
</div>
<!-- toc disabled -->
</div>
</div>
<div class="sect1">
<h2 id="Target_Audience"><a class="anchor" href="#Target_Audience"></a><a class="link" href="#Target_Audience">1. Target Audience</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>This document is a guide to the setup, administration, and configuration
of WildFly.</p>
</div>
<div class="sect2">
<h3 id="prerequisites"><a class="anchor" href="#prerequisites"></a><a class="link" href="#prerequisites">1.1. Prerequisites</a></h3>
<div class="paragraph">
<p>Before continuing, you should know how to download, install and run
WildFly. For more information on these steps, refer here:
<a href="Getting_Started_Guide.html">Getting Started Guide</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="examples-in-this-guide"><a class="anchor" href="#examples-in-this-guide"></a><a class="link" href="#examples-in-this-guide">1.2. Examples in this guide</a></h3>
<div class="paragraph">
<p>The examples in this guide are largely expressed as XML configuration
file excerpts, or by using a representation of the de-typed management
model.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Core_management_concepts"><a class="anchor" href="#Core_management_concepts"></a><a class="link" href="#Core_management_concepts">2. Core management concepts</a></h2>
<div class="sectionbody">
<!-- toc disabled -->
<div class="sect2">
<h3 id="Operating_modes"><a class="anchor" href="#Operating_modes"></a><a class="link" href="#Operating_modes">2.1. Operating mode</a></h3>
<div class="paragraph">
<p>WildFly can be booted in two different modes. A <em>managed domain</em> allows
you to run and manage a multi-server topology. Alternatively, you can
run a <em>standalone server</em> instance.</p>
</div>
<div class="sect3">
<h4 id="standalone-server"><a class="anchor" href="#standalone-server"></a><a class="link" href="#standalone-server">2.1.1. Standalone Server</a></h4>
<div class="paragraph">
<p>For many use cases, the centralized management capability available via
a managed domain is not necessary. For these use cases, a WildFly
instance can be run as a "standalone server". A standalone server
instance is an independent process, much like an JBoss Application
Server 3, 4, 5, or 6 instance is. Standalone instances can be launched
via the <code>standalone.sh</code> or <code>standalone.bat</code> launch scripts.</p>
</div>
<div class="paragraph">
<p>If more than one standalone instance is launched and multi-server
management is desired, it is the user&#8217;s responsibility to coordinate
management across the servers. For example, to deploy an application
across all of the standalone servers, the user would need to
individually deploy the application on each server.</p>
</div>
<div class="paragraph">
<p>It is perfectly possible to launch multiple standalone server instances
and have them form an HA cluster, just like it was possible with JBoss
Application Server 3, 4, 5 and 6.</p>
</div>
</div>
<div class="sect3">
<h4 id="managed-domain"><a class="anchor" href="#managed-domain"></a><a class="link" href="#managed-domain">2.1.2. Managed Domain</a></h4>
<div class="paragraph">
<p>One of the primary new features of WildFly is the ability to manage
multiple WildFly instances from a single control point. A collection of
such servers is referred to as the members of a "domain" with a single
Domain Controller process acting as the central management control
point. All of the WildFly instances in the domain share a common
management policy, with the Domain Controller acting to ensure that each
server is configured according to that policy. Domains can span multiple
physical (or virtual) machines, with all WildFly instances on a given
host under the control of a special Host Controller process. One Host
Controller instance is configured to act as the central Domain
Controller. The Host Controller on each host interacts with the Domain
Controller to control the lifecycle of the application server instances
running on its host and to assist the Domain Controller in managing
them.</p>
</div>
<div class="paragraph">
<p>When you launch a WildFly managed domain on a host (via the <code>domain.sh</code>
or <code>domain.bat</code> launch scripts) your intent is to launch a Host
Controller and usually at least one WildFly instance. On one of the
hosts the Host Controller should be configured to act as the Domain
Controller. See <a href="#Domain_Setup">Domain Setup</a> for details.</p>
</div>
<div class="paragraph">
<p>The following is an example managed domain topology:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="DC-HC-Server.png" alt="images/DC-HC-Server.png"></span></p>
</div>
<div class="sect4">
<h5 id="host"><a class="anchor" href="#host"></a><a class="link" href="#host">Host</a></h5>
<div class="paragraph">
<p>Each "Host" box in the above diagram represents a physical or virtual
host. A physical host can contain zero, one or more server instances.</p>
</div>
</div>
<div class="sect4">
<h5 id="host-controller"><a class="anchor" href="#host-controller"></a><a class="link" href="#host-controller">Host Controller</a></h5>
<div class="paragraph">
<p>When the domain.sh or domain.bat script is run on a host, a process
known as a Host Controller is launched. The Host Controller is solely
concerned with server management; it does not itself handle application
server workloads. The Host Controller is responsible for starting and
stopping the individual application server processes that run on its
host, and interacts with the Domain Controller to help manage them.</p>
</div>
<div class="paragraph">
<p>Each Host Controller by default reads its configuration from the
<code>domain/configuration/host.xml</code> file located in the unzipped WildFly
installation on its host&#8217;s filesystem. The <code>host.xml</code> file contains
configuration information that is specific to the particular host.
Primarily:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the listing of the names of the actual WildFly instances that are
meant to run off of this installation.</p>
</li>
<li>
<p>configuration of how the Host Controller is to contact the Domain
Controller to register itself and access the domain configuration. This
may either be configuration of how to find and contact a remote Domain
Controller, or a configuration telling the Host Controller to itself act
as the Domain Controller.</p>
</li>
<li>
<p>configuration of items that are specific to the local physical
installation. For example, named interface definitions declared in
<code>domain.xml</code> (see below) can be mapped to an actual machine-specific IP
address in <code>host.xml</code>. Abstract path names in <code>domain.xml</code> can be mapped
to actual filesystem paths in <code>host.xml</code>.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="domain-controller"><a class="anchor" href="#domain-controller"></a><a class="link" href="#domain-controller">Domain Controller</a></h5>
<div class="paragraph">
<p>One Host Controller instance is configured to act as the central
management point for the entire domain, i.e. to be the Domain
Controller. The primary responsibility of the Domain Controller is to
maintain the domain&#8217;s central management policy, to ensure all Host
Controllers are aware of its current contents, and to assist the Host
Controllers in ensuring any running application server instances are
configured in accordance with this policy. This central management
policy is stored by default in the <code>domain/configuration/domain.xml</code>
file in the unzipped WildFly installation on Domain Controller&#8217;s host&#8217;s
filesystem.</p>
</div>
<div class="paragraph">
<p>A <code>domain.xml</code> file must be located in the <code>domain/configuration</code>
directory of an installation that&#8217;s meant to run the Domain Controller.
It does not need to be present in installations that are not meant to
run a Domain Controller; i.e. those whose Host Controller is configured
to contact a remote Domain Controller. The presence of a <code>domain.xml</code>
file on such a server does no harm.</p>
</div>
<div class="paragraph">
<p>The <code>domain.xml</code> file includes, among other things, the configuration of
the various "profiles" that WildFly instances in the domain can be
configured to run. A profile configuration includes the detailed
configuration of the various subsystems that comprise that profile (e.g.
an embedded JBoss Web instance is a subsystem; a JBoss TS transaction
manager is a subsystem, etc). The domain configuration also includes the
definition of groups of sockets that those subsystems may open. The
domain configuration also includes the definition of "server groups":</p>
</div>
</div>
<div class="sect4">
<h5 id="server-group"><a class="anchor" href="#server-group"></a><a class="link" href="#server-group">Server Group</a></h5>
<div class="paragraph">
<p>A server group is set of server instances that will be managed and
configured as one. In a managed domain each application server instance
is a member of a server group. (Even if the group only has a single
server, the server is still a member of a group.) It is the
responsibility of the Domain Controller and the Host Controllers to
ensure that all servers in a server group have a consistent
configuration. They should all be configured with the same profile and
they should have the same deployment content deployed.</p>
</div>
<div class="paragraph">
<p>The domain can have multiple server groups. The above diagram shows two
server groups, "ServerGroupA" and "ServerGroupB". Different server
groups can be configured with different profiles and deployments; for
example in a domain with different tiers of servers ﻿providing different
services. Different server groups can also run the same profile and have
the same deployments; for example to support rolling application upgrade
scenarios where a complete service outage is avoided by first upgrading
the application on one server group and then upgrading a second server
group.</p>
</div>
<div class="paragraph">
<p>An example server group definition is as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;deployments&gt;</span>
        <span class="tag">&lt;deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">foo.war_v1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">runtime-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">foo.war</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bar.ear</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">runtime-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bar.ear</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/deployments&gt;</span>
<span class="tag">&lt;/server-group&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>A server-group configuration includes the following required attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>name&#8201;&#8212;&#8201;the name of the server group</p>
</li>
<li>
<p>profile&#8201;&#8212;&#8201;the name of the profile the servers in the group should run</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In addition, the following optional elements are available:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>socket-binding-group&#8201;&#8212;&#8201;specifies the name of the default socket
binding group to use on servers in the group. Can be overridden on a
per-server basis in <code>host.xml</code>. If not provided in the <code>server-group</code>
element, it must be provided for each server in <code>host.xml</code>.</p>
</li>
<li>
<p>deployments&#8201;&#8212;&#8201;the deployment content that should be deployed on the
servers in the group.</p>
</li>
<li>
<p>deployment-overlays&#8201;&#8212;&#8201;the overlays and their associated deployments.</p>
</li>
<li>
<p>system-properties&#8201;&#8212;&#8201;system properties that should be set on all
servers in the group</p>
</li>
<li>
<p>jvm&#8201;&#8212;&#8201;default jvm settings for all servers in the group. The Host
Controller will merge these settings with any provided in <code>host.xml</code> to
derive the settings to use to launch the server&#8217;s JVM. See
<a href="#JVM_settings">JVM settings</a> for further details.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="server"><a class="anchor" href="#server"></a><a class="link" href="#server">Server</a></h5>
<div class="paragraph">
<p>Each "Server" in the above diagram represents an actual application
server instance. The server runs in a separate JVM process from the Host
Controller. The Host Controller is responsible for launching that
process. (In a managed domain the end user cannot directly launch a
server process from the command line.)</p>
</div>
<div class="paragraph">
<p>The Host Controller synthesizes the server&#8217;s configuration by combining
elements from the domain wide configuration (from <code>domain.xml</code> ) and the
host-specific configuration (from <code>host.xml</code> ).</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="deciding-between-running-standalone-servers-or-a-managed-domain"><a class="anchor" href="#deciding-between-running-standalone-servers-or-a-managed-domain"></a><a class="link" href="#deciding-between-running-standalone-servers-or-a-managed-domain">2.1.3. Deciding between running standalone servers or a managed domain</a></h4>
<div class="paragraph">
<p>Which use cases are appropriate for managed domain and which are
appropriate for standalone servers? A managed domain is all about
coordinated multi-server management&#8201;&#8212;&#8201;with it WildFly provides a
central point through which users can manage multiple servers, with rich
capabilities to keep those servers' configurations consistent and the
ability to roll out configuration changes (including deployments) to the
servers in a coordinated fashion.</p>
</div>
<div class="paragraph">
<p>It&#8217;s important to understand that the choice between a managed domain
and standalone servers is all about how your servers are managed, not
what capabilities they have to service end user requests. This
distinction is particularly important when it comes to high availability
clusters. It&#8217;s important to understand that HA functionality is
orthogonal to running standalone servers or a managed domain. That is, a
group of standalone servers can be configured to form an HA cluster. The
domain and standalone modes determine how the servers are managed, not
what capabilities they provide.</p>
</div>
<div class="paragraph">
<p>So, given all that:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A single server installation gains nothing from running in a managed
domain, so running a standalone server is a better choice.</p>
</li>
<li>
<p>For multi-server production environments, the choice of running a
managed domain versus standalone servers comes down to whether the user
wants to use the centralized management capabilities a managed domain
provides. Some enterprises have developed their own sophisticated
multi-server management capabilities and are comfortable coordinating
changes across a number of independent WildFly instances. For these
enterprises, a multi-server architecture comprised of individual
standalone servers is a good option.</p>
</li>
<li>
<p>Running a standalone server is better suited for most development
scenarios. Any individual server configuration that can be achieved in a
managed domain can also be achieved in a standalone server, so even if
the application being developed will eventually run in production on a
managed domain installation, much (probably most) development can be
done using a standalone server.</p>
</li>
<li>
<p>Running a managed domain mode can be helpful in some advanced
development scenarios; i.e. those involving interaction between multiple
WildFly instances. Developers may find that setting up various servers
as members of a domain is an efficient way to launch a multi-server
cluster.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="General_configuration_concepts"><a class="anchor" href="#General_configuration_concepts"></a><a class="link" href="#General_configuration_concepts">2.2. General configuration concepts</a></h3>
<div class="paragraph">
<p>For both a managed domain or a standalone server, a number of common
configuration concepts apply:</p>
</div>
<div class="sect3">
<h4 id="extensions"><a class="anchor" href="#extensions"></a><a class="link" href="#extensions">2.2.1. Extensions</a></h4>
<div class="paragraph">
<p>An extension is a module that extends the core capabilities of the
server. The WildFly core is very simple and lightweight; most of the
capabilities people associate with an application server are provided
via extensions. An extension is packaged as a module in the <code>modules</code>
folder. The user indicates that they want a particular extension to be
available by including an <code>&lt;extension/&gt;</code> element naming its module in
the <code>domain.xml</code> or <code>standalone.xml</code> file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extensions&gt;</span>
    [...]
    <span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.transactions</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.webservices</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.weld</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    [...]
    <span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.wildfly.extension.undertow</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/extensions&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="profiles-and-subsystems"><a class="anchor" href="#profiles-and-subsystems"></a><a class="link" href="#profiles-and-subsystems">2.2.2. Profiles and Subsystems</a></h4>
<div class="paragraph">
<p>The most significant part of the configuration in <code>domain.xml</code> and
<code>standalone.xml</code> is the configuration of one (in <code>standalone.xml</code>) or
more (in <code>domain.xml</code>) "profiles". A profile is a named set of subsystem
configurations. A subsystem is an added set of capabilities added to the
core server by an extension (see "Extensions" above). A subsystem
provides servlet handling capabilities; a subsystem provides an Jakarta Enterprise Beans
container; a subsystem provides Jakarta Transactions, etc. A profile is a named list of
subsystems, along with the details of each subsystem&#8217;s configuration. A
profile with a large number of subsystems results in a server with a
large set of capabilities. A profile with a small, focused set of
subsystems will have fewer capabilities but a smaller footprint.</p>
</div>
<div class="paragraph">
<p>The content of an individual profile configuration looks largely the
same in <code>domain.xml</code> and <code>standalone.xml</code>. The only difference is
<code>standalone.xml</code> is only allowed to have a single profile element (the
profile the server will run), while <code>domain.xml</code> can have many profiles,
each of which can be mapped to one or more groups of servers.</p>
</div>
<div class="paragraph">
<p>The contents of individual subsystem configurations look exactly the
same between <code>domain.xml</code> and <code>standalone.xml</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="paths"><a class="anchor" href="#paths"></a><a class="link" href="#paths">2.2.3. Paths</a></h4>
<div class="paragraph">
<p>A logical name for a filesystem path. The <code>domain.xml</code>, <code>host.xml</code> and
<code>standalone.xml</code> configurations all include a section where paths can be
declared. Other sections of the configuration can then reference those
paths by their logical name, rather than having to include the full
details of the path (which may vary on different machines). For example,
the logging subsystem configuration includes a reference to the "
`jboss.server.log.dir`" path that points to the server&#8217;s " `log`"
directory.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;file</span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.log.dir</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server.log</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>WildFly automatically provides a number of standard paths without any
need for the user to configure them in a configuration file:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>jboss.home</code>.dir - the root directory of the WildFly distribution</p>
</li>
<li>
<p><code>user.home</code> - user&#8217;s home directory</p>
</li>
<li>
<p><code>user.dir</code> - user&#8217;s current working directory</p>
</li>
<li>
<p><code>java.home</code> - java installation directory</p>
</li>
<li>
<p><code>jboss.server.base.dir</code> - root directory for an individual server
instance</p>
</li>
<li>
<p><code>jboss.server.config.dir</code> - directory the server will use for
configuration file storage</p>
</li>
<li>
<p><code>jboss.server.data.dir</code> - directory the server will use for persistent
data file storage</p>
</li>
<li>
<p><code>jboss.server.log.dir</code> - directory the server will use for log file
storage</p>
</li>
<li>
<p><code>jboss.server.temp.dir</code> - directory the server will use for temporary
file storage</p>
</li>
<li>
<p><code>jboss.controller.temp.dir</code> - directory the server will use for
temporary file storage</p>
</li>
<li>
<p><code>jboss.domain.servers.dir</code> - directory under which a host controller
will create the working area for individual server instances (managed
domain mode only)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Users can add their own paths or override all except the first 5 of the
above by adding a <code>&lt;path/&gt;</code> element to their configuration file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;path</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">example</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">example</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.data.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The attributes are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code>&#8201;&#8212;&#8201;the name of the path.</p>
</li>
<li>
<p><code>path</code>&#8201;&#8212;&#8201;the actual filesystem path. Treated as an absolute path,
unless the 'relative-to' attribute is specified, in which case the value
is treated as relative to that path.</p>
</li>
<li>
<p><code>relative-to</code>&#8201;&#8212;&#8201;(optional) the name of another previously named path,
or of one of the standard paths provided by the system.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A <code>&lt;path/&gt;</code> element in a <code>domain.xml</code> need not include anything more
than the <code>name</code> attribute; i.e. it need not include any information
indicating what the actual filesystem path is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;path</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">x</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Such a configuration simply says, "There is a path named 'x' that other
parts of the <code>domain.xml</code> configuration can reference. The actual
filesystem location pointed to by 'x' is host-specific and will be
specified in each machine&#8217;s <code>host.xml</code> file." If this approach is used,
there must be a path element in each machine&#8217;s <code>host.xml</code> that specifies
what the actual filesystem path is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;path</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">x</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/var/x</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>A <code>&lt;path/&gt;</code> element in a <code>standalone.xml</code> must include the specification
of the actual filesystem path.</p>
</div>
</div>
<div class="sect3">
<h4 id="interfaces"><a class="anchor" href="#interfaces"></a><a class="link" href="#interfaces">2.2.4. Interfaces</a></h4>
<div class="paragraph">
<p>A logical name for a network interface/IP address/host name to which
sockets can be bound. The <code>domain.xml</code>, <code>host.xml</code> and <code>standalone.xml</code>
configurations all include a section where interfaces can be declared.
Other sections of the configuration can then reference those interfaces
by their logical name, rather than having to include the full details of
the interface (which may vary on different machines). An interface
configuration includes the logical name of the interface as well as
information specifying the criteria to use for resolving the actual
physical address to use. See <a href="#Interfaces_and_ports">Interfaces
and ports</a> for further details.</p>
</div>
<div class="paragraph">
<p>An <code>&lt;interface/&gt;</code> element in a <code>domain.xml</code> need not include anything
more than the <code>name</code> attribute; i.e. it need not include any information
indicating what the actual IP address associated with the name is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">internal</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Such a configuration simply says, "There is an interface named
'internal' that other parts of the domain.xml configuration can
reference. The actual IP address pointed to by 'internal' is
host-specific and will be specified in each machine&#8217;s host.xml file." If
this approach is used, there must be an interface element in each
machine&#8217;s <code>host.xml</code> that specifies the criteria for determining the IP
address:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">internal</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;nic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">eth1</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/interface&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>An <code>&lt;interface/&gt;</code> element in a <code>standalone.xml</code> must include the
criteria for determining the IP address.</p>
</div>
<div class="paragraph">
<p>See <a href="#interface-declarations">Interface declarations</a>
for full details.</p>
</div>
</div>
<div class="sect3">
<h4 id="socket-bindings-and-socket-binding-groups"><a class="anchor" href="#socket-bindings-and-socket-binding-groups"></a><a class="link" href="#socket-bindings-and-socket-binding-groups">2.2.5. Socket Bindings and Socket Binding Groups</a></h4>
<div class="paragraph">
<p>A socket binding is a named configuration for a socket.</p>
</div>
<div class="paragraph">
<p>The <code>domain.xml</code> and <code>standalone.xml</code> configurations both include a
section where named socket configurations can be declared. Other
sections of the configuration can then reference those sockets by their
logical name, rather than having to include the full details of the
socket configuration (which may vary on different machines).
See <a href="#socket-binding-groups">Socket Binding Groups</a>
for full details.</p>
</div>
</div>
<div class="sect3">
<h4 id="system-properties"><a class="anchor" href="#system-properties"></a><a class="link" href="#system-properties">2.2.6. System Properties</a></h4>
<div class="paragraph">
<p>System property values can be set in a number of places in <code>domain.xml</code>,
<code>host.xml</code> and <code>standalone.xml</code>. The values in <code>standalone.xml</code> are set
as part of the server boot process. Values in <code>domain.xml</code> and
<code>host.xml</code> are applied to servers when they are launched.</p>
</div>
<div class="paragraph">
<p>When a system property is configured in <code>domain.xml</code> or <code>host.xml</code>, the
servers it ends up being applied to depends on where it is set. Setting
a system property in a child element directly under the <code>domain.xml</code>
root results in the property being set on all servers. Setting it in a
<code>&lt;system-property/&gt;</code> element inside a <code>&lt;server-group/&gt;</code> element in
domain.xml results in the property being set on all servers in the
group. Setting it in a child element directly under the <code>host.xml</code> root
results in the property being set on all servers controlled by that
host&#8217;s Host Controller. Finally, setting it in a <code>&lt;system-property/&gt;</code>
element inside a <code>&lt;server/&gt;</code> element in <code>host.xml</code> result in the
property being set on that server. The same property can be configured
in multiple locations, with a value in a <code>&lt;server/&gt;</code> element taking
precedence over a value specified directly under the <code>host.xml</code> root
element, the value in a <code>host.xml</code> taking precedence over anything from
<code>domain.xml</code>, and a value in a <code>&lt;server-group/&gt;</code> element taking
precedence over a value specified directly under the <code>domain.xml</code> root
element.</p>
</div>
</div>
<div class="sect3">
<h4 id="script-configuration-files"><a class="anchor" href="#script-configuration-files"></a><a class="link" href="#script-configuration-files">2.2.7. Script Configuration Files</a></h4>
<div class="paragraph">
<p>Scripts are located in the <code>$JBOSS_HOME/bin</code> directory. Within this directory you will find script configuration files
for standalone and domain startup scripts for each platform. These files can be used to configure your environment
without having to edit the scripts themselves. For example, you can configure the <code>JAVA_OPTS</code> environment variable to
configure the JVM before the container is launched.</p>
</div>
<div class="sect4">
<h5 id="standalone-script-configuration-files"><a class="anchor" href="#standalone-script-configuration-files"></a><a class="link" href="#standalone-script-configuration-files">Standalone Script Configuration Files:</a></h5>
<div class="ulist">
<ul>
<li>
<p><code>standalone.conf</code> invoked from <code>standalone.sh</code></p>
</li>
<li>
<p><code>standalone.conf.bat</code> invoked from <code>standalone.bat</code></p>
</li>
<li>
<p><code>standalone.conf.ps1</code> invoked from <code>standalone.ps1</code></p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="domain-script-configuration-files"><a class="anchor" href="#domain-script-configuration-files"></a><a class="link" href="#domain-script-configuration-files">Domain Script Configuration Files:</a></h5>
<div class="ulist">
<ul>
<li>
<p><code>domain.conf</code> invoked from <code>domain.sh</code></p>
</li>
<li>
<p><code>domain.conf.bat</code> invoked from <code>domain.bat</code></p>
</li>
<li>
<p><code>domain.conf.ps1</code> invoked from <code>domain.ps1</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default, these are in the <code>$JBOSS_HOME/bin</code> directory. However, you can set the <code>STANDALONE_CONF</code> environment
variable for standalone servers or <code>DOMAIN_CONF</code> environment variable for domain servers with a value of the
absolute path to the file.</p>
</div>
</div>
<div class="sect4">
<h5 id="common-script-configuration-files"><a class="anchor" href="#common-script-configuration-files"></a><a class="link" href="#common-script-configuration-files">Common Script Configuration Files</a></h5>
<div class="paragraph">
<p>Starting with WildFly 23, common configuration files were introduced. These files are invoked from every script in the
<code>$JBOSS_HOME/bin</code> directory. While these configuration files are not present in the directory by default, they
can be added. You can simply just add the <code>common.conf</code> configuration file for the script type you want to
execute and all scripts in the directory will invoke the configuration script.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>common.conf</code> for bash scripts</p>
</li>
<li>
<p><code>common.conf.bat</code> for Windows batch scripts</p>
</li>
<li>
<p><code>common.conf.ps1</code> for PowerShell scripts</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can also set the <code>COMMON_CONF</code> environment variable to have this configuration script live outside the
<code>$JBOSS_HOME/bin</code> directory.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you provide a common configuration file it will be invoked before the standalone and domain script
configuration files. For example invoking <code>standalone.sh</code> first invokes the <code>common.conf</code> then later invokes
the <code>standalone.conf</code>.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="management-resources"><a class="anchor" href="#management-resources"></a><a class="link" href="#management-resources">2.3. Management resources</a></h3>
<div class="paragraph">
<p>When WildFly parses your configuration files at boot, or when you use
one of the AS&#8217;s <a href="#Management_Clients">Management Clients</a> you are
adding, removing or modifying <em>management resources</em> in the AS&#8217;s
internal management model. A WildFly management resource has the
following characteristics:</p>
</div>
<div class="sect3">
<h4 id="address"><a class="anchor" href="#address"></a><a class="link" href="#address">2.3.1. Address</a></h4>
<div class="paragraph">
<p>All WildFly management resources are organized in a tree. The path to
the node in the tree for a particular resource is its <em>address</em>. Each
segment in a resource&#8217;s address is a key/value pair:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The key is the resource&#8217;s <em>type</em>, in the context of its parent. So,
for example, the root resource for a standalone server has children of
type <code>subsystem</code>, <code>interface</code>, <code>socket-binding</code>, etc. The resource for
the subsystem that provides the AS&#8217;s webserver capability has children
of type <code>connector</code> and <code>virtual-server</code>. The resource for the subsystem
that provides the AS&#8217;s messaging server capability has, among others,
children of type <code>jms-queue</code> and <code>jms-topic</code>.</p>
</li>
<li>
<p>The value is the name of a particular resource of the given type, e.g
<code>web</code> or <code>messaging</code> for subsystems or <code>http</code> or <code>https</code> for web
subsystem connectors.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The full address for a resource is the ordered list of key/value pairs
that lead from the root of the tree to the resource. Typical notation is
to separate the elements in the address with a '/' and to separate the
key and the value with an '=':</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/subsystem=undertow/server=default-server/http-listener=default</code></p>
</li>
<li>
<p><code>/subsystem=messaging/jms-queue=testQueue</code></p>
</li>
<li>
<p><code>/interface=public</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When using the HTTP API, a '/' is used to separate the key and the value
instead of an '=':</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://localhost:9990/management/subsystem/undertow/server/default-server/http-listener/default" class="bare">http://localhost:9990/management/subsystem/undertow/server/default-server/http-listener/default</a></code></p>
</li>
<li>
<p><code><a href="http://localhost:9990/management/subsystem/messaging/jms-queue/testQueue" class="bare">http://localhost:9990/management/subsystem/messaging/jms-queue/testQueue</a></code></p>
</li>
<li>
<p><code><a href="http://localhost:9990/management/interface/public" class="bare">http://localhost:9990/management/interface/public</a></code></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="operations"><a class="anchor" href="#operations"></a><a class="link" href="#operations">2.3.2. Operations</a></h4>
<div class="paragraph">
<p>Querying or modifying the state of a resource is done via an operation.
An operation has the following characteristics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A string name</p>
</li>
<li>
<p>Zero or more named parameters. Each parameter has a string name, and a
value of type <code>org.jboss.dmr.ModelNode</code> (or, when invoked via the CLI,
the text representation of a <code>ModelNode</code>; when invoked via the HTTP API,
the JSON representation of a <code>ModelNode</code>.) Parameters may be optional.</p>
</li>
<li>
<p>A return value, which will be of type <code>org.jboss.dmr.ModelNode</code> (or,
when invoked via the CLI, the text representation of a <code>ModelNode</code>; when
invoked via the HTTP API, the JSON representation of a <code>ModelNode</code>.)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Every resource except the root resource will have an <code>add</code> operation and
should have a <code>remove</code> operation ("should" because in WildFly 27 many do
not). The parameters for the <code>add</code> operation vary depending on the
resource. The <code>remove</code> operation has no parameters.</p>
</div>
<div class="paragraph">
<p>There are also a number of "global" operations that apply to all
resources. See <a href="#Global_operations">Global operations</a> for full
details.</p>
</div>
<div class="paragraph">
<p>The operations a resource supports can themselves be determined by
invoking an operation: the <code>read-operation-names</code> operation. Once the
name of an operation is known, details about its parameters and return
value can be determined by invoking the <code>read-operation-description</code>
operation. For example, to learn the names of the operations exposed by
the root resource for a standalone server, and then learn the full
details of one of them, via the CLI one would:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :read-operation-names
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        &quot;add-namespace&quot;,
        &quot;add-schema-location&quot;,
        &quot;delete-snapshot&quot;,
        &quot;full-replace-deployment&quot;,
        &quot;list-snapshots&quot;,
        &quot;read-attribute&quot;,
        &quot;read-children-names&quot;,
        &quot;read-children-resources&quot;,
        &quot;read-children-types&quot;,
        &quot;read-config-as-xml&quot;,
        &quot;read-operation-description&quot;,
        &quot;read-operation-names&quot;,
        &quot;read-resource&quot;,
        &quot;read-resource-description&quot;,
        &quot;reload&quot;,
        &quot;remove-namespace&quot;,
        &quot;remove-schema-location&quot;,
        &quot;replace-deployment&quot;,
        &quot;shutdown&quot;,
        &quot;take-snapshot&quot;,
        &quot;upload-deployment-bytes&quot;,
        &quot;upload-deployment-stream&quot;,
        &quot;upload-deployment-url&quot;,
        &quot;validate-address&quot;,
        &quot;write-attribute&quot;
    ]
}
[standalone@localhost:9990 /] :read-operation-description(name=upload-deployment-url)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;operation-name&quot; =&gt; &quot;upload-deployment-url&quot;,
        &quot;description&quot; =&gt; &quot;Indicates that the deployment content available at the included URL should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.&quot;,
        &quot;request-properties&quot; =&gt; {&quot;url&quot; =&gt; {
            &quot;type&quot; =&gt; STRING,
            &quot;description&quot; =&gt; &quot;The URL at which the deployment content is available for upload to the domain's or standalone server's deployment content repository.. Note that the URL must be accessible from the target of the operation (i.e. the Domain Controller or standalone server).&quot;,
            &quot;required&quot; =&gt; true,
            &quot;min-length&quot; =&gt; 1,
            &quot;nillable&quot; =&gt; false
        }},
        &quot;reply-properties&quot; =&gt; {
            &quot;type&quot; =&gt; BYTES,
            &quot;description&quot; =&gt; &quot;The hash of managed deployment content that has been uploaded to the domain's or standalone server's deployment content repository.&quot;,
            &quot;min-length&quot; =&gt; 20,
            &quot;max-length&quot; =&gt; 20,
            &quot;nillable&quot; =&gt; false
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#descriptions">Descriptions</a>
below for more on how to learn about the operations a resource exposes.</p>
</div>
</div>
<div class="sect3">
<h4 id="attributes"><a class="anchor" href="#attributes"></a><a class="link" href="#attributes">2.3.3. Attributes</a></h4>
<div class="paragraph">
<p>Management resources expose information about their state as attributes.
Attributes have string name, and a value of type
<code>org.jboss.dmr.ModelNode</code> (or: for the CLI, the text representation of a
<code>ModelNode</code>; for HTTP API, the JSON representation of a <code>ModelNode</code>.)</p>
</div>
<div class="paragraph">
<p>Attributes can either be read-only or read-write. Reading and writing
attribute values is done via the global <code>read-attribute</code> and
<code>write-attribute</code> operations.</p>
</div>
<div class="paragraph">
<p>The <code>read-attribute</code> operation takes a single parameter "name" whose
value is a the name of the attribute. For example, to read the "port"
attribute of a socket-binding resource via the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /socket-binding-group=standard-sockets/socket-binding=https:read-attribute(name=port)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; 8443
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If an attribute is writable, the <code>write-attribute</code> operation is used to
mutate its state. The operation takes two parameters:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – the name of the attribute</p>
</li>
<li>
<p><code>value</code> – the value of the attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, to read the "port" attribute of a socket-binding resource
via the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /socket-binding-group=standard-sockets/socket-binding=https:write-attribute(name=port,value=8444)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Attributes can have one of two possible <em>storage types</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>CONFIGURATION</strong> – means the value of the attribute is stored in the
persistent configuration; i.e. in the <code>domain.xml</code>, <code>host.xml</code> or
<code>standalone.xml</code> file from which the resource&#8217;s configuration was read.</p>
</li>
<li>
<p><strong>RUNTIME</strong> – the attribute value is only available from a running
server; the value is not stored in the persistent configuration. A
metric (e.g. number of requests serviced) is a typical example of a
RUNTIME attribute.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The values of all of the attributes a resource exposes can be obtained
via the <code>read-resource</code> operation, with the "include-runtime" parameter
set to "true". For example, from the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=undertow/server=default-server/http-listener=default:read-resource(include-runtime=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;allow-encoded-slash&quot; =&gt; false,
        &quot;allow-equals-in-cookie-value&quot; =&gt; false,
        &quot;always-set-keep-alive&quot; =&gt; true,
        &quot;buffer-pipelined-data&quot; =&gt; true,
        &quot;buffer-pool&quot; =&gt; &quot;default&quot;,
        &quot;bytes-received&quot; =&gt; 0L,
        &quot;bytes-sent&quot; =&gt; 0L,
        &quot;certificate-forwarding&quot; =&gt; false,
        &quot;decode-url&quot; =&gt; true,
        &quot;disallowed-methods&quot; =&gt; [&quot;TRACE&quot;],
        &quot;enable-http2&quot; =&gt; false,
        &quot;enabled&quot; =&gt; true,
        &quot;error-count&quot; =&gt; 0L,
        &quot;max-buffered-request-size&quot; =&gt; 16384,
        &quot;max-connections&quot; =&gt; undefined,
        &quot;max-cookies&quot; =&gt; 200,
        &quot;max-header-size&quot; =&gt; 1048576,
        &quot;max-headers&quot; =&gt; 200,
        &quot;max-parameters&quot; =&gt; 1000,
        &quot;max-post-size&quot; =&gt; 10485760L,
        &quot;max-processing-time&quot; =&gt; 0L,
        &quot;no-request-timeout&quot; =&gt; undefined,
        &quot;processing-time&quot; =&gt; 0L,
        &quot;proxy-address-forwarding&quot; =&gt; false,
        &quot;read-timeout&quot; =&gt; undefined,
        &quot;receive-buffer&quot; =&gt; undefined,
        &quot;record-request-start-time&quot; =&gt; false,
        &quot;redirect-socket&quot; =&gt; &quot;https&quot;,
        &quot;request-count&quot; =&gt; 0L,
        &quot;request-parse-timeout&quot; =&gt; undefined,
        &quot;resolve-peer-address&quot; =&gt; false,
        &quot;send-buffer&quot; =&gt; undefined,
        &quot;socket-binding&quot; =&gt; &quot;http&quot;,
        &quot;tcp-backlog&quot; =&gt; undefined,
        &quot;tcp-keep-alive&quot; =&gt; undefined,
        &quot;url-charset&quot; =&gt; &quot;UTF-8&quot;,
        &quot;worker&quot; =&gt; &quot;default&quot;,
        &quot;write-timeout&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Omit the "include-runtime" parameter (or set it to "false") to limit
output to those attributes whose values are stored in the persistent
configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=undertow/server=default-server/http-listener=default:read-resource(include-runtime=false)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;allow-encoded-slash&quot; =&gt; false,
        &quot;allow-equals-in-cookie-value&quot; =&gt; false,
        &quot;always-set-keep-alive&quot; =&gt; true,
        &quot;buffer-pipelined-data&quot; =&gt; true,
        &quot;buffer-pool&quot; =&gt; &quot;default&quot;,
        &quot;certificate-forwarding&quot; =&gt; false,
        &quot;decode-url&quot; =&gt; true,
        &quot;disallowed-methods&quot; =&gt; [&quot;TRACE&quot;],
        &quot;enable-http2&quot; =&gt; false,
        &quot;enabled&quot; =&gt; true,
        &quot;max-buffered-request-size&quot; =&gt; 16384,
        &quot;max-connections&quot; =&gt; undefined,
        &quot;max-cookies&quot; =&gt; 200,
        &quot;max-header-size&quot; =&gt; 1048576,
        &quot;max-headers&quot; =&gt; 200,
        &quot;max-parameters&quot; =&gt; 1000,
        &quot;max-post-size&quot; =&gt; 10485760L,
        &quot;no-request-timeout&quot; =&gt; undefined,
        &quot;proxy-address-forwarding&quot; =&gt; false,
        &quot;read-timeout&quot; =&gt; undefined,
        &quot;receive-buffer&quot; =&gt; undefined,
        &quot;record-request-start-time&quot; =&gt; false,
        &quot;redirect-socket&quot; =&gt; &quot;https&quot;,
        &quot;request-parse-timeout&quot; =&gt; undefined,
        &quot;resolve-peer-address&quot; =&gt; false,
        &quot;send-buffer&quot; =&gt; undefined,
        &quot;socket-binding&quot; =&gt; &quot;http&quot;,
        &quot;tcp-backlog&quot; =&gt; undefined,
        &quot;tcp-keep-alive&quot; =&gt; undefined,
        &quot;url-charset&quot; =&gt; &quot;UTF-8&quot;,
        &quot;worker&quot; =&gt; &quot;default&quot;,
        &quot;write-timeout&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#descriptions">Descriptions</a>
below for how to learn more about the attributes a particular resource
exposes.</p>
</div>
<div class="sect4">
<h5 id="overridden-attribute-value"><a class="anchor" href="#overridden-attribute-value"></a><a class="link" href="#overridden-attribute-value">Override an Attribute Value with an Environment Variable</a></h5>
<div class="paragraph">
<p>It is possible to override the value of any simple attribute by providing an environment variable with a name
that maps to the attribute (and its resource).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Complex attributes (which have their <code>type</code> set to <code>LIST, OBJECT</code>, or <code>PROPERTY</code>) can not be overridden using an environment variable.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If there is an environment variable with such a name, the management resource will use the value of this environment variable
when the management resource validates and sets the attribute value.
This takes place before the attribute value is resolved (if it contains an expression) or corrected.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This feature is disabled by default. To enable it, the environment variable <code>WILDFLY_OVERRIDING_ENV_VARS</code> must be set (its value is not relevant):</p>
</div>
<div class="paragraph">
<p><code>export WILDFLY_OVERRIDING_ENV_VARS=1</code></p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect5">
<h6 id="mapping-between-the-resource-address-and-attribute-and-the-environment-variable"><a class="anchor" href="#mapping-between-the-resource-address-and-attribute-and-the-environment-variable"></a><a class="link" href="#mapping-between-the-resource-address-and-attribute-and-the-environment-variable">Mapping between the resource address and attribute and the environment variable</a></h6>
<div class="paragraph">
<p>The name of the environment variable is based on the address of the resource and the name of the attribute:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>take the address of the resource (e.g. <code>/subsystem=undertow/server=default-server/http-listener=default</code>)</p>
<div class="ulist">
<ul>
<li>
<p><code>/subsystem=undertow/server=default-server/http-listener=default</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>remove the leading slash (<code>/</code>)</p>
<div class="ulist">
<ul>
<li>
<p><code>subsystem=undertow/server=default-server/http-listener=default</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>append <strong>two underscores</strong> (<code>__</code>) and the name of the attribute (e.g. <code>proxy-address-forwarding</code>)</p>
<div class="ulist">
<ul>
<li>
<p><code>subsystem=undertow/server=default-server/http-listener=default__proxy-address-forwarding</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>Replace all non-alphanumeric characters with an underscore (<code>_</code>) and put it in upper case</p>
<div class="ulist">
<ul>
<li>
<p><code>SUBSYSTEM_UNDERTOW_SERVER_DEFAULT_SERVER_HTTP_LISTENER_DEFAULT__PROXY_ADDRESS_FORWARDING</code></p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>If WildFly is started with that environment variable, the value of the <code>proxy-address-forwarding</code> attribute on the
<code>/subsystem=undertow/server=default-server/http-listener=default</code> will be set to the value of the environment variable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="nowrap">$ WILDFLY_OVERRIDING_ENV_VARS=1 \
  SUBSYSTEM_UNDERTOW_SERVER_DEFAULT_SERVER_HTTP_LISTENER_DEFAULT__PROXY_ADDRESS_FORWARDING=false \
  ./bin/standalone.sh
$ ./bin/jboss-cli.sh -c --command=&quot;/subsystem=undertow/server=default-server/http-listener=default:read-attribute(name=proxy-address-forwarding)&quot;
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;false&quot;</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If an attribute value is determined from an environment variable, the next time the configuration is persisted, that value from the environment variable will be persisted.
Until an operation triggers such persistence of the configuration file, the configuration file will not reflect the current running configuration.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="children"><a class="anchor" href="#children"></a><a class="link" href="#children">2.3.4. Children</a></h4>
<div class="paragraph">
<p>Management resources may support child resources. The
<a href="#address"><em>types</em> of children</a> a
resource supports (e.g. <code>connector</code> for the web subsystem resource) can
be obtained by querying the resource&#8217;s description (see
<a href="#descriptions">Descriptions</a> below)
or by invoking the <code>read-children-types</code> operation. Once you know the
legal child types, you can query the names of all children of a given
type by using the global <code>read-children-types</code> operation. The operation
takes a single parameter "child-type" whose value is the type. For
example, a resource representing a socket binding group has children. To
find the type of those children and the names of resources of that type
via the CLI one could:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="yaml">[<span class="error">standalone@localhost:9990 /] /socket-binding-group=standard-sockets:read-children-types</span>
{
    <span class="error">&quot;outcome&quot; =&gt; &quot;success&quot;,</span>
    <span class="error">&quot;result&quot; =&gt; [&quot;socket-binding&quot;]</span>
}
[<span class="error">standalone@localhost:9990 /] /socket-binding-group=standard-sockets:read-children-names(child-type=socket-binding)</span>
{
    <span class="error">&quot;outcome&quot; =&gt; &quot;success&quot;,</span>
    <span class="error">&quot;result&quot; =&gt; [</span>
        <span class="error">&quot;http&quot;,</span>
        <span class="error">&quot;https&quot;,</span>
        <span class="error">&quot;jmx-connector-registry&quot;,</span>
        <span class="error">&quot;jmx-connector-server&quot;,</span>
        <span class="error">&quot;jndi&quot;,</span>
        <span class="error">&quot;remoting&quot;,</span>
        <span class="error">&quot;txn-recovery-environment&quot;,</span>
        <span class="error">&quot;txn-status-manager&quot;</span>
    ]
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="descriptions"><a class="anchor" href="#descriptions"></a><a class="link" href="#descriptions">2.3.5. Descriptions</a></h4>
<div class="paragraph">
<p>All resources expose metadata that describes their attributes,
operations and child types. This metadata is itself obtained by invoking
one or more of the <a href="#Global_operations">global operations</a> each
resource supports. We showed examples of the <code>read-operation-names</code>,
<code>read-operation-description</code>, <code>read-children-types</code> and
<code>read-children-names</code> operations above.</p>
</div>
<div class="paragraph">
<p>The <code>read-resource-description</code> operation can be used to find the
details of the attributes and child types associated with a resource.
For example, using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="yaml">[<span class="error">standalone@localhost:9990 /] /socket-binding-group=standard-sockets:read-resource-description</span>
{
    <span class="error">&quot;outcome&quot; =&gt; &quot;success&quot;,</span>
    <span class="error">&quot;result&quot; =&gt; {</span>
        <span class="error">&quot;description&quot; =&gt; &quot;Contains a list of socket configurations.&quot;,</span>
        <span class="error">&quot;head-comment-allowed&quot; =&gt; true,</span>
        <span class="error">&quot;tail-comment-allowed&quot; =&gt; false,</span>
        <span class="error">&quot;attributes&quot; =&gt; {</span>
            <span class="error">&quot;name&quot; =&gt; {</span>
                <span class="error">&quot;type&quot; =&gt; STRING,</span>
                <span class="error">&quot;description&quot; =&gt; &quot;The name of the socket binding group.&quot;,</span>
                <span class="error">&quot;required&quot; =&gt; true,</span>
                <span class="error">&quot;head-comment-allowed&quot; =&gt; false,</span>
                <span class="error">&quot;tail-comment-allowed&quot; =&gt; false,</span>
                <span class="error">&quot;access-type&quot; =&gt; &quot;read-only&quot;,</span>
                <span class="error">&quot;storage&quot; =&gt; &quot;configuration&quot;</span>
            },
            <span class="error">&quot;default-interface&quot; =&gt; {</span>
                <span class="error">&quot;type&quot; =&gt; STRING,</span>
                <span class="error">&quot;description&quot; =&gt; &quot;Name of an interface that should be used as the interface for any sockets that do not explicitly declare one.&quot;,</span>
                <span class="error">&quot;required&quot; =&gt; true,</span>
                <span class="error">&quot;head-comment-allowed&quot; =&gt; false,</span>
                <span class="error">&quot;tail-comment-allowed&quot; =&gt; false,</span>
                <span class="error">&quot;access-type&quot; =&gt; &quot;read-write&quot;,</span>
                <span class="error">&quot;storage&quot; =&gt; &quot;configuration&quot;</span>
            },
            <span class="error">&quot;port-offset&quot; =&gt; {</span>
                <span class="error">&quot;type&quot; =&gt; INT,</span>
                <span class="error">&quot;description&quot; =&gt; &quot;Increment to apply to the base port values defined in the socket bindings to derive the runtime values to use on this server.&quot;,</span>
                <span class="error">&quot;required&quot; =&gt; false,</span>
                <span class="error">&quot;head-comment-allowed&quot; =&gt; true,</span>
                <span class="error">&quot;tail-comment-allowed&quot; =&gt; false,</span>
                <span class="error">&quot;access-type&quot; =&gt; &quot;read-write&quot;,</span>
                <span class="error">&quot;storage&quot; =&gt; &quot;configuration&quot;</span>
            }
        },
        <span class="error">&quot;operations&quot; =&gt; {},</span>
        <span class="error">&quot;children&quot; =&gt; {&quot;socket-binding&quot; =&gt; {</span>
            <span class="error">&quot;description&quot; =&gt; &quot;The individual socket configurtions.&quot;,</span>
            <span class="error">&quot;min-occurs&quot; =&gt; 0,</span>
            <span class="error">&quot;model-description&quot; =&gt; undefined</span>
        }}
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the
<code>"operations" &#8658; }} in the output above. If the command had included the {{operations</code>
parameter (i.e.
<code>/socket-binding-group=standard-sockets:read-resource-description(operations=true)</code>)
the output would have included the description of each operation
supported by the resource.</p>
</div>
<div class="paragraph">
<p>See the <a href="#Global_operations">Global operations</a> section for
details on other parameters supported by the <code>read-resource-description</code>
operation and all the other globally available operations.</p>
</div>
</div>
<div class="sect3">
<h4 id="comparison-to-jmx-mbeans"><a class="anchor" href="#comparison-to-jmx-mbeans"></a><a class="link" href="#comparison-to-jmx-mbeans">2.3.6. Comparison to JMX MBeans</a></h4>
<div class="paragraph">
<p>WildFly management resources are conceptually quite similar to Open
MBeans. They have the following primary differences:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>WildFly management resources are organized in a tree structure. The
order of the key value pairs in a resource&#8217;s address is significant, as
it defines the resource&#8217;s position in the tree. The order of the key
properties in a JMX <code>ObjectName</code> is not significant.</p>
</li>
<li>
<p>In an Open MBean attribute values, operation parameter values and
operation return values must either be one of the simple JDK types
(String, Boolean, Integer, etc) or implement either the
<code>javax.management.openmbean.CompositeData</code> interface or the
<code>javax.management.openmbean.TabularData</code> interface. WildFly management
resource attribute values, operation parameter values and operation
return values are all of type <code>org.jboss.dmr.ModelNode</code>.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="basic-structure-of-the-management-resource-trees"><a class="anchor" href="#basic-structure-of-the-management-resource-trees"></a><a class="link" href="#basic-structure-of-the-management-resource-trees">2.3.7. Basic structure of the management resource trees</a></h4>
<div class="paragraph">
<p>As noted above, management resources are organized in a tree structure.
The structure of the tree depends on whether you are running a
standalone server or a managed domain.</p>
</div>
<div class="sect4">
<h5 id="standalone-server-2"><a class="anchor" href="#standalone-server-2"></a><a class="link" href="#standalone-server-2">Standalone server</a></h5>
<div class="paragraph">
<p>The structure of the managed resource tree is quite close to the
structure of the <code>standalone.xml</code> configuration file.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The root resource</p>
<div class="ulist">
<ul>
<li>
<p><code>extension</code> – extensions installed in the server</p>
</li>
<li>
<p><code>path</code> – paths available on the server</p>
</li>
<li>
<p><code>system-property</code> – system properties set as part of the
configuration (i.e. not on the command line)</p>
</li>
<li>
<p><code>core-service=management</code> – the server&#8217;s core management services</p>
</li>
<li>
<p><code>core-service=service-container</code> – resource for the JBoss MSC
<code>ServiceContainer</code> that&#8217;s at the heart of the AS</p>
</li>
<li>
<p><code>subsystem</code> – the subsystems installed on the server. The bulk of the
management model will be children of type <code>subsystem</code></p>
</li>
<li>
<p><code>interface</code> – interface configurations</p>
</li>
<li>
<p><code>socket-binding-group</code> – the central resource for the server&#8217;s socket
bindings</p>
<div class="ulist">
<ul>
<li>
<p><code>socket-binding</code> – individual socket binding configurations</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>deployment</code> – available deployments on the server</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="managed-domain-2"><a class="anchor" href="#managed-domain-2"></a><a class="link" href="#managed-domain-2">Managed domain</a></h5>
<div class="paragraph">
<p>In a managed domain, the structure of the managed resource tree spans
the entire domain, covering both the domain wide configuration (e.g.
what&#8217;s in <code>domain.xml</code>, the host specific configuration for each host
(e.g. what&#8217;s in <code>host.xml</code>, and the resources exposed by each running
application server. The Host Controller processes in a managed domain
provide access to all or part of the overall resource tree. How much is
available depends on whether the management client is interacting with
the Host Controller that is acting as the Domain Controller. If
the Host Controller is the Domain Controller, then the section of
the tree for each host is available. If the Host Controller is a secondary Host Controller
to a remote Domain Controller, then only the portion of the tree
associated with that host is available.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The root resource for the entire domain. The persistent configuration
associated with this resource and its children, except for those of type
<code>host</code>, is persisted in the <code>domain.xml</code> file on the Domain Controller.</p>
<div class="ulist">
<ul>
<li>
<p><code>extension</code> – extensions available in the domain</p>
</li>
<li>
<p><code>path</code> – paths available on across the domain</p>
</li>
<li>
<p><code>system-property</code> – system properties set as part of the
configuration (i.e. not on the command line) and available across the
domain</p>
</li>
<li>
<p><code>profile</code> – sets of subsystem configurations that can be assigned to
server groups</p>
<div class="ulist">
<ul>
<li>
<p><code>subsystem</code> – configuration of subsystems that are part of the
profile</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>interface</code> – interface configurations</p>
</li>
<li>
<p><code>socket-binding-group</code> – sets of socket bindings configurations that
can be applied to server groups</p>
<div class="ulist">
<ul>
<li>
<p><code>socket-binding</code> – individual socket binding configurations</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>deployment</code> – deployments available for assignment to server groups</p>
</li>
<li>
<p>deployment-overlay&#8201;&#8212;&#8201;deployment-overlays content available to
overlay deployments in server groups</p>
</li>
<li>
<p><code>server-group</code> – server group configurations</p>
</li>
<li>
<p>host – the individual Host Controllers. Each child of this type
represents the root resource for a particular host. The persistent
configuration associated with one of these resources or its children is
persisted in the host&#8217;s <code>host.xml</code> file.</p>
<div class="ulist">
<ul>
<li>
<p><code>path</code> – paths available on each server on the host</p>
</li>
<li>
<p><code>system-property</code> – system properties to set on each server on the
host</p>
</li>
<li>
<p><code>core-service=management</code> – the Host Controller&#8217;s core management
services</p>
</li>
<li>
<p><code>interface</code> – interface configurations that apply to the Host
Controller or servers on the host</p>
</li>
<li>
<p><code>jvm</code> – JVM configurations that can be applied when launching
servers</p>
</li>
<li>
<p><code>server-config</code> – configuration describing how the Host Controller
should launch a server; what server group configuration to use, and any
server-specific overrides of items specified in other resources</p>
</li>
<li>
<p><code>server</code> – the root resource for a running server. Resources from
here and below are not directly persisted; the domain-wide and host
level resources contain the persistent configuration that drives a
server</p>
<div class="ulist">
<ul>
<li>
<p><code>extension</code> – extensions installed in the server</p>
</li>
<li>
<p><code>path</code> – paths available on the server</p>
</li>
<li>
<p><code>system-property</code> – system properties set as part of the
configuration (i.e. not on the command line)</p>
</li>
<li>
<p><code>core-service=management</code> – the server&#8217;s core management services</p>
</li>
<li>
<p><code>core-service=service-container</code> – resource for the JBoss MSC
<code>ServiceContainer</code> that&#8217;s at the heart of the AS</p>
</li>
<li>
<p><code>subsystem</code> – the subsystems installed on the server. The bulk of
the management model will be children of type <code>subsystem</code></p>
</li>
<li>
<p><code>interface</code> – interface configurations</p>
</li>
<li>
<p><code>socket-binding-group</code> – the central resource for the server&#8217;s
socket bindings</p>
<div class="ulist">
<ul>
<li>
<p><code>socket-binding</code> – individual socket binding configurations</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>deployment</code> – available deployments on the server</p>
</li>
<li>
<p>deployment-overlay&#8201;&#8212;&#8201;available overlays on the server</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Management_Clients"><a class="anchor" href="#Management_Clients"></a><a class="link" href="#Management_Clients">3. Management Clients</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>WildFly offers three different approaches to configure and manage
servers: a web interface, a command line client and a set of XML
configuration files. Regardless of the approach you choose, the
configuration is always synchronized across the different views and
finally persisted to the XML files.</p>
</div>
<div class="sect2">
<h3 id="web-management-interface"><a class="anchor" href="#web-management-interface"></a><a class="link" href="#web-management-interface">3.1. Web Management Interface</a></h3>
<div class="paragraph">
<p>The web interface is a GWT application that uses the HTTP management API
to configure a management domain or standalone server.</p>
</div>
<div class="sect3">
<h4 id="http-management-endpoint"><a class="anchor" href="#http-management-endpoint"></a><a class="link" href="#http-management-endpoint">3.1.1. HTTP Management Endpoint</a></h4>
<div class="paragraph">
<p>The HTTP API endpoint is the entry point for management clients that
rely on the HTTP protocol to integrate with the management layer. It
uses a JSON encoded protocol and a de-typed, RPC style API to describe
and execute management operations against a managed domain or standalone
server. It&#8217;s used by the web console, but offers integration
capabilities for a wide range of other clients too.</p>
</div>
<div class="paragraph">
<p>The HTTP API endpoint is co-located with either the domain controller or
a standalone server. By default, it runs on port 9990:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;management-interfaces&gt;</span>
 [...]
  <span class="tag">&lt;http-interface</span> <span class="attribute-name">http-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;http-upgrade</span> <span class="attribute-name">enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">sasl-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-sasl-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;socket-binding</span> <span class="attribute-name">http</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/http-interface&gt;</span>
<span class="tag">&lt;management-interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone.xml or
domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>The HTTP API Endpoint serves two different contexts. One for executing
management operations and another one that allows you to access the web
interface:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Domain API: <a href="http://&lt;host&gt;:9990/management" class="bare">http://&lt;host&gt;:9990/management</a></p>
</li>
<li>
<p>Web Console: <a href="http://&lt;host&gt;:9990/console" class="bare">http://&lt;host&gt;:9990/console</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="accessing-the-web-console"><a class="anchor" href="#accessing-the-web-console"></a><a class="link" href="#accessing-the-web-console">3.1.2. Accessing the web console</a></h4>
<div class="paragraph">
<p>The web console is served through the same port as the HTTP management
API. It can be accessed by pointing your browser to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://&lt;host&gt;:9990/console" class="bare">http://&lt;host&gt;:9990/console</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Default URL</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
By default the web interface can be accessed here:
<a href="http://localhost:9990/console" class="bare">http://localhost:9990/console</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="custom-http-headers"><a class="anchor" href="#custom-http-headers"></a><a class="link" href="#custom-http-headers">3.1.3. Custom HTTP Headers</a></h4>
<div class="paragraph">
<p>For the responses returned from the HTTP management interface it is also possible to define custom constant HTTP headers that will be added to any response based on matching a configured prefix against the request path.</p>
</div>
<div class="paragraph">
<p>As an example it could be desirable to add a HTTP header <code>X-Help</code> which points users to the correct location to obtain assistance.  The following management operation can be executed within the CLI to activate returning this header on all requests.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /]  /core-service=management/management-interface=http-interface: \
    write-attribute(name=constant-headers, value=[{path=&quot;/&quot;, \
    headers=[{name=&quot;X-Help&quot;, value=&quot;wildfly.org&quot;}]}])</code></pre>
</div>
</div>
<div class="paragraph">
<p>The responses to all requests to the HTTP management interface will now include the header <code>X-Help</code> with the value <code>wildfly.org</code>.</p>
</div>
<div class="paragraph">
<p>The resulting configuration will look like: -</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;management-interfaces&gt;</span>
  <span class="tag">&lt;http-interface</span> <span class="attribute-name">http-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;http-upgrade</span> <span class="attribute-name">enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">sasl-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-sasl-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;socket-binding</span> <span class="attribute-name">http</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;constant-headers&gt;</span>
            <span class="tag">&lt;header-mapping</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;header</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">X-Help</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">wildfly.org</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;/header-mapping&gt;</span>
        <span class="tag">&lt;/constant-headers&gt;</span>
    <span class="tag">&lt;/http-interface&gt;</span>
<span class="tag">&lt;/management-interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The example here has illustrated adding a single header for all requests matching the path prefix <code>/</code> i.e. every request.  More advanced mappings can be defined by specifying a mapping for a more specific path prefix such as <code>/management</code>.</p>
</div>
<div class="paragraph">
<p>If a request matches multiple mappings such as a request to <code>/management</code> where mappings for <code>/</code> and <code>/management</code> have been specified the headers from all of the mappings will be applied to the corresponding request.</p>
</div>
<div class="paragraph">
<p>Within a single mapping it is also possible to define multiple headers which should be set on the corresponding response.</p>
</div>
<div class="paragraph">
<p>As the <code>constant-headers</code> attribute is set verification will be performed to verify that the HTTP headers specified are only making use of allowed characters as specified in the HTTP specification RFCs.</p>
</div>
<div class="paragraph">
<p>Additionally as they have special handling within the management interface overriding the following headers is disallowed and attempts to set these will result in an error being reported.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>Connection</code></p>
</li>
<li>
<p><code>Content-Length</code></p>
</li>
<li>
<p><code>Content-Type</code></p>
</li>
<li>
<p><code>Date</code></p>
</li>
<li>
<p><code>Transfer-Encoding</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The configured headers are set at the very end of processing the request immediately before the response is returned to the client, this will mean any of the configured headers will override the same headers set by the corresponding endpoint.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Command_Line_Interface"><a class="anchor" href="#Command_Line_Interface"></a><a class="link" href="#Command_Line_Interface">3.2. Command Line Interface</a></h3>
<div class="paragraph">
<p>The Command Line Interface (CLI) is a management tool for a managed
domain or standalone server. It allows a user to connect to the domain
controller or a standalone server and execute management operations
available through the de-typed management model.</p>
</div>
<div class="sect3">
<h4 id="running-the-cli"><a class="anchor" href="#running-the-cli"></a><a class="link" href="#running-the-cli">3.2.1. Running the CLI</a></h4>
<div class="paragraph">
<p>Depending on the operating system, the CLI is launched using
<code>jboss-cli.sh</code> or <code>jboss-cli.bat</code> located in the WildFly <code>bin</code>
directory. For further information on the default directory structure,
please consult the " <a href="Getting_Started_Guide.html">Getting Started
Guide</a>".</p>
</div>
<div class="paragraph">
<p>The first thing to do after the CLI has started is to connect to a
managed WildFly instance. This is done using the command <em>connect</em>, e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./bin/jboss-cli.sh
You are disconnected at the moment. Type 'connect' to connect to the server
or 'help' for the list of supported commands.
[disconnected /]
 
[disconnected /] connect
[domain@localhost:9990 /]
 
[domain@localhost:9990 /] quit
Closed connection to localhost:9990</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>localhost:9990</code> is the default host and port combination for the
WildFly CLI client.</p>
</div>
<div class="paragraph">
<p>The host and the port of the server can be provided as an optional
parameter, if the server is not listening on localhost:9990.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./bin/jboss-cli.sh
You are disconnected at the moment. Type 'connect' to connect to the server
[disconnected /] connect 192.168.0.10:9990
Connected to standalone controller at 192.168.0.1:9990</code></pre>
</div>
</div>
<div class="paragraph">
<p>The :9990 is not required as the CLI will use port 9990 by default. The
port needs to be provided if the server is listening on some other port.</p>
</div>
<div class="paragraph">
<p>To terminate the session type <em>quit</em>.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The jboss-cli script accepts a --connect parameter: ./jboss-cli.sh
--connect
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The --controller parameter can be used to specify the host and port of
the server: ./jboss-cli.sh --connect --controller=192.168.0.1:9990</p>
</div>
<div class="paragraph">
<p>Help is also available:</p>
</div>
<div class="paragraph">
<p>In order to list the set of commands that are currently available in the current context
use the option <em>--commands</em> (NB: the following examples are not displaying an
exhaustive set of CLI commands, more and/or different commands could be available
in your running CLI instance):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] help --commands
Commands available in the current context:
batch               connection-factory  deployment-overlay  if                  patch               reload              try
cd                  connection-info     echo                jdbc-driver-info    pwd                 rollout-plan        undeploy
clear               data-source         echo-dmr            jms-queue           quit                run-batch           unset
command             deploy              help                jms-topic           read-attribute      set                 version
connect             deployment-info     history             ls                  read-operation      shutdown            xa-data-source
To read a description of a specific command execute 'help &lt;command name&gt;'.</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <em>help</em> command can print help for any command or operation. For operations,
the operation description is formatted as a command help (synopsis, description and
options). Some commands (eg: <em>patch</em>) expose two levels of documentation. A high
level description for the command itself and a dedicated help content for each action (eg: <em>apply</em>).
The help documentation of each command makes it clear if this two levels are available or not.</p>
</div>
<div class="paragraph">
<p>Use Tab-completion to discover the set of commands and operations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>help &lt;TAB&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The list of all commands (enabled or not) is displayed.</p>
</div>
<div class="paragraph">
<p>Examples</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Display the help of the <em>patch</em> command:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>help patch</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Display the help of the <em>apply</em> action of the <em>patch</em> command:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>help patch apply</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Display the description of the <em>elytron</em> <em>key-store</em> resource <em>add</em> operation
formatted as a command help content:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>help /subsystem=elytron/key-store=?:add</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="cli-keyboard-navigation"><a class="anchor" href="#cli-keyboard-navigation"></a><a class="link" href="#cli-keyboard-navigation">3.2.2. Keyboard navigation</a></h4>
<div class="paragraph">
<p>In order to efficiently edit commands, the CLI allows you to navigate the words
 and characters of a command using the keyboard.</p>
</div>
<div class="paragraph">
<p>NB: Part of this navigation is platform dependent.</p>
</div>
<div class="sect4">
<h5 id="go-left-back-one-word"><a class="anchor" href="#go-left-back-one-word"></a><a class="link" href="#go-left-back-one-word">Go left (back) one word</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Alt+B</em> : Linux, Solaris, HP-UX, Windows.</p>
</li>
<li>
<p><em>Ctrl+LeftArrow</em>: Linux, Solaris, HP-UX.</p>
</li>
<li>
<p><em>Alt+LeftArrow</em>: Mac OSX.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="go-right-forward-one-word"><a class="anchor" href="#go-right-forward-one-word"></a><a class="link" href="#go-right-forward-one-word">Go right (forward) one word</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Alt+F</em> : Linux, Solaris, HP-UX, Windows.</p>
</li>
<li>
<p><em>Ctrl+RightArrow</em>: Linux, Solaris, HP-UX.</p>
</li>
<li>
<p><em>Alt+RightArrow</em>: Mac OSX.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="go-to-the-beginning-of-the-line"><a class="anchor" href="#go-to-the-beginning-of-the-line"></a><a class="link" href="#go-to-the-beginning-of-the-line">Go to the beginning of the line</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Ctrl+A</em>: All supported platforms.</p>
</li>
<li>
<p><em>HOME</em>:  Linux, Solaris, HP-UX, Windows</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="go-to-the-end-of-the-line"><a class="anchor" href="#go-to-the-end-of-the-line"></a><a class="link" href="#go-to-the-end-of-the-line">Go to the end of the line</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Ctrl+E</em>: All supported platforms.</p>
</li>
<li>
<p><em>END</em>: Linux, Solaris, HP-UX, Windows</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="go-left-back-one-character"><a class="anchor" href="#go-left-back-one-character"></a><a class="link" href="#go-left-back-one-character">Go left (back) one character</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Ctrl+B</em> or <em>LeftArrow</em>: All supported platforms.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="go-right-forward-one-character"><a class="anchor" href="#go-right-forward-one-character"></a><a class="link" href="#go-right-forward-one-character">Go right (forward) one character</a></h5>
<div class="ulist">
<ul>
<li>
<p><em>Ctrl+F</em> or <em>RightArrow</em>: All supported platforms.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="cli-non-interactive-mode"><a class="anchor" href="#cli-non-interactive-mode"></a><a class="link" href="#cli-non-interactive-mode">3.2.3. Non-interactive Mode</a></h4>
<div class="paragraph">
<p>The CLI can also be run in non-interactive mode to support scripts and
other types of command line or batch processing. The --command and
--commands arguments can be used to pass a command or a list of commands
to execute. Additionally a --file argument is supported which enables
CLI commands to be provided from a text file.</p>
</div>
<div class="paragraph">
<p>For example the following command can be used to list all the current
deployments</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ ./bin/jboss-cli.sh --connect --commands=ls\ deployment
sample.war
business.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>The output can be combined with other shell commands for further
processing, for example to find out what .war files are deployed:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ ./bin/jboss-cli.sh --connect --commands=ls\ deployment | grep war
sample.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to match a command with its output, you can provide the option
--echo-command (or add the XML element &lt;echo-command&gt; to the CLI
configuration file) in order to make the CLI to include the prompt<br>
command + options in the output. With this option enabled, any executed
command will be added to the output.</p>
</div>
</div>
<div class="sect3">
<h4 id="command-timeout"><a class="anchor" href="#command-timeout"></a><a class="link" href="#command-timeout">3.2.4. Command timeout</a></h4>
<div class="paragraph">
<p>By default CLI command and operation executions are not timely bounded.
It means that a command never ending its execution will make the CLI
process to be stuck and unresponsive. To protect the CLI from this
behavior, one can set a command execution timeout.</p>
</div>
<div class="sect4">
<h5 id="command-timeout-behavior"><a class="anchor" href="#command-timeout-behavior"></a><a class="link" href="#command-timeout-behavior">Command Timeout behavior</a></h5>
<div class="paragraph">
<p>In interactive mode, when a timeout occurs, an error message is
displayed then the console prompt is made available to type new
commands. In non interactive mode (executing a script or a list of
commands), when a timeout occurs, an exception is thrown and the CLI
execution is stopped. In both modes (interactive and non interactive),
when a timeout occurs, the CLI will make a best effort to cancel the
associated server side activities.</p>
</div>
</div>
<div class="sect4">
<h5 id="configuring-the-command-timeout"><a class="anchor" href="#configuring-the-command-timeout"></a><a class="link" href="#configuring-the-command-timeout">Configuring the Command timeout</a></h5>
<div class="ulist">
<ul>
<li>
<p>Add the XML element <em>&lt;command-timeout&gt;\{num
seconds}&lt;/command-timeout&gt;</em> to the CLI XML configuration file.</p>
</li>
<li>
<p>Add the option - <em>-command-timeout=\{num seconds}</em> to the CLI command
line. This will override any value set in the XML configuration file.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="managing-the-command-timeout"><a class="anchor" href="#managing-the-command-timeout"></a><a class="link" href="#managing-the-command-timeout">Managing the Command Timeout</a></h5>
<div class="paragraph">
<p>Once the CLI is running, the timeout can be adjusted to cope with the
commands to execute. For example a batch command will need a longer
timeout than a non batch one. The command <em>command-timeout</em> allows to
get, set and reset the command timeout.</p>
</div>
</div>
<div class="sect4">
<h5 id="retrieving-the-command-timeout"><a class="anchor" href="#retrieving-the-command-timeout"></a><a class="link" href="#retrieving-the-command-timeout">Retrieving the command timeout</a></h5>
<div class="paragraph">
<p>The command <em>command-timeout get</em> displays the current timeout in
seconds. A timeout of 0 means no timeout.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] command-timeout get
0</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="setting-the-command-timeout"><a class="anchor" href="#setting-the-command-timeout"></a><a class="link" href="#setting-the-command-timeout">Setting the command timeout</a></h5>
<div class="paragraph">
<p>The command <em>command-timeout set</em> update the timeout value to a number
of seconds. If a timeout has been set via configuration (XML file or
option), it is overridden by the <em>set</em> action.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] command-timeout set 10</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="resetting-the-command-timeout"><a class="anchor" href="#resetting-the-command-timeout"></a><a class="link" href="#resetting-the-command-timeout">Resetting the command timeout</a></h5>
<div class="paragraph">
<p>The command <em>command-timeout reset \{config|default}</em> allows to set the
timeout to its configuration value (XML file or option) or default value
(0 second). If no configuration value is set, resetting to the
configuration value sets the timeout to its default value (0 seconds).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] command-timeout reset config
[standalone@localhost:9990 /] command-timeout reset default</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="default-native-management-interface-security"><a class="anchor" href="#default-native-management-interface-security"></a><a class="link" href="#default-native-management-interface-security">3.2.5. Default Native Management Interface Security</a></h4>
<div class="paragraph">
<p>The native interface shares the same security configuration as the http
interface, however we also support a local authentication mechanism
which means that the CLI can authenticate against the local WildFly
instance without prompting the user for a username and password. This
mechanism only works if the user running the CLI has read access to the
standalone/tmp/auth folder or domain/tmp/auth folder under the
respective WildFly installation - if the local mechanism fails then the
CLI will fallback to prompting for a username and password for a user
configured as in <a href="#Default_HTTP_Interface_Security">Default HTTP Interface Security</a>.</p>
</div>
<div class="paragraph">
<p>Establishing a CLI connection to a remote server will require a username
and password by default.</p>
</div>
</div>
<div class="sect3">
<h4 id="operation-requests"><a class="anchor" href="#operation-requests"></a><a class="link" href="#operation-requests">3.2.6. Operation Requests</a></h4>
<div class="paragraph">
<p>Operation requests allow for low level interaction with the management
model. They are different from the high level commands (i.e.
<em>create-jms-queue</em>) in that they allow you to read and modify the server
configuration as if you were editing the XML configuration files
directly. The configuration is represented as a tree of addressable
resources, where each node in the tree (aka resource) offers a set of
operations to execute.</p>
</div>
<div class="paragraph">
<p>An operation request basically consists of three parts: The <em>address</em>,
an <em>operation name</em> and an optional set of <em>parameters</em>.</p>
</div>
<div class="paragraph">
<p>The formal specification for an operation request is:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[/node-type=node-name (/node-type=node-name)*] : operation-name [( [parameter-name=parameter-value (,parameter-name=parameter-value)*] )]</pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/root-logger=ROOT:change-root-log-level(level=WARN)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Tab Completion</p>
</div>
<div class="paragraph">
<p>Tab-completion is supported for all commands and options, i.e.
node-types and node-names, operation names and parameter names.</p>
</div>
<div class="paragraph">
<p>In operation Tab-completion, required parameters have a name terminated by the
'*' character. This helps identify which are the parameters that must be set in order to
construct a valid operation. Furthermore, Tab-completion does not propose
parameters that are alternatives of parameters already present in the operation.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/deployment=myapp:add(&lt;TAB&gt;
!  content*  enabled  runtime-name</code></pre>
</div>
</div>
<div class="paragraph">
<p>The parameter <em>content</em> is required and completion advertises it with a '*' character.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/deployment=myapp:add-content(content=[{&lt;TAB&gt;
bytes*  hash*  input-stream-index*  target-path*  url*</code></pre>
</div>
</div>
<div class="paragraph">
<p><em>bytes</em>, <em>hash</em>, <em>input-stream-index</em> and <em>url</em> are required but also alternatives
(only one of them can be set). As soon as one of these parameter has been set, the
others are no longer proposed by completion.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/deployment=myapp:add-content(content=[{url=myurl,&lt;TAB&gt;
/deployment=myapp:add-content(content=[{url=myurl,target-path</code></pre>
</div>
</div>
<div class="paragraph">
<p><em>target-path</em> argument is automatically inlined in the command.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
We are also considering adding aliases that are less verbose for the user, and
will translate into the corresponding operation requests in the
background.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Whitespaces between the separators in the operation request strings are
not significant.</p>
</div>
<div class="sect4">
<h5 id="addressing-resources"><a class="anchor" href="#addressing-resources"></a><a class="link" href="#addressing-resources">Addressing resources</a></h5>
<div class="paragraph">
<p>Operation requests might not always have the address part or the
parameters. E.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>:read-resource</code></pre>
</div>
</div>
<div class="paragraph">
<p>which will list all the node types for the current node.</p>
</div>
<div class="paragraph">
<p>To syntactically disambiguate between the commands and operations,
operations require one of the following prefixes:</p>
</div>
<div class="paragraph">
<p>To execute an operation against the current node, e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>cd subsystem=logging
:read-resource(recursive=&quot;true&quot;)</code></pre>
</div>
</div>
<div class="paragraph">
<p>To execute an operation against a child node of the current node, e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>cd subsystem=logging
./root-logger=ROOT:change-root-log-level(level=WARN)</code></pre>
</div>
</div>
<div class="paragraph">
<p>To execute an operation against the root node, e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/:read-resource</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="available-operation-types-and-descriptions"><a class="anchor" href="#available-operation-types-and-descriptions"></a><a class="link" href="#available-operation-types-and-descriptions">Available Operation Types and Descriptions</a></h5>
<div class="paragraph">
<p>The operation types can be distinguished between common operations that
exist on any node and specific operations that belong to a particular
configuration resource (i.e. subsystem). The common operations are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>add</p>
</li>
<li>
<p>read-attribute</p>
</li>
<li>
<p>read-children-names</p>
</li>
<li>
<p>read-children-resources</p>
</li>
<li>
<p>read-children-types</p>
</li>
<li>
<p>read-operation-description</p>
</li>
<li>
<p>read-operation-names</p>
</li>
<li>
<p>read-resource</p>
</li>
<li>
<p>read-resource-description</p>
</li>
<li>
<p>remove</p>
</li>
<li>
<p>validate-address</p>
</li>
<li>
<p>write-attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For a list of specific operations (e.g. operations that relate to the
logging subsystem) you can always query the model itself. For example,
to read the operations supported by the logging subsystem resource on a
standalone server:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[[standalone@localhost:9990 /] /subsystem=logging:read-operation-names
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [
       &quot;add&quot;,
       &quot;change-root-log-level&quot;,
       &quot;read-attribute&quot;,
       &quot;read-children-names&quot;,
       &quot;read-children-resources&quot;,
       &quot;read-children-types&quot;,
       &quot;read-operation-description&quot;,
       &quot;read-operation-names&quot;,
       &quot;read-resource&quot;,
       &quot;read-resource-description&quot;,
       &quot;remove-root-logger&quot;,
       &quot;root-logger-assign-handler&quot;,
       &quot;root-logger-unassign-handler&quot;,
       &quot;set-root-logger&quot;,
       &quot;validate-address&quot;,
       &quot;write-attribute&quot;
   ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, the logging resource offers four additional operations,
namely <em>root-logger-assign-handler</em>, <em>root-logger-unassign-handler</em>,
<em>set-root-logger</em> and <em>remove-root-logger</em>.</p>
</div>
<div class="paragraph">
<p>Further documentation about a resource or operation can be retrieved
through the description:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=logging:read-operation-description(name=change-root-log-level)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; {
       &quot;operation-name&quot; =&gt; &quot;change-root-log-level&quot;,
       &quot;description&quot; =&gt; &quot;Change the root logger level.&quot;,
       &quot;request-properties&quot; =&gt; {&quot;level&quot; =&gt; {
           &quot;type&quot; =&gt; STRING,
           &quot;description&quot; =&gt; &quot;The log level specifying which message levels will be logged by this logger.
                            Message levels lower than this value will be discarded.&quot;,
           &quot;required&quot; =&gt; true
       }}
   }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Full model</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
To see the full model enter <code>:read-resource(recursive=true)</code>.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="command-history"><a class="anchor" href="#command-history"></a><a class="link" href="#command-history">3.2.7. Command History</a></h4>
<div class="paragraph">
<p>Command (and operation request) history is enabled by default. The
history is kept both in-memory and in a file on the disk, i.e. it is
preserved between command line sessions. The history file name is
.jboss-cli-history and is automatically created in the user&#8217;s home
directory. When the command line interface is launched this file is read
and the in-memory history is initialized with its content.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
While in the command line session, you can use the arrow keys to go back
and forth in the history of commands and operations.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To manipulate the history you can use the <em>history</em> command. If executed
without any arguments, it will print all the recorded commands and
operations (up to the configured maximum, which defaults to 500) from
the in-memory history.</p>
</div>
<div class="paragraph">
<p><em>history</em> supports three optional arguments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>disable</em> - will disable history expansion (but will not clear the
previously recorded history);</p>
</li>
<li>
<p><em>enabled</em> - will re-enable history expansion (starting from the last
recorded command before the history expansion was disabled);</p>
</li>
<li>
<p><em>clear</em> - will clear the in-memory history (but not the file one).</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="json-and-dmr-output"><a class="anchor" href="#json-and-dmr-output"></a><a class="link" href="#json-and-dmr-output">3.2.8. JSON and DMR output</a></h4>
<div class="paragraph">
<p>By default the CLI prints operation results using the DMR textual syntax. There are
two ways to make the CLI to display JSON:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>--output-json</em> option when launching the CLI.</p>
</li>
<li>
<p><em>&lt;output-json&gt;</em> XML element added to <em>jboss-cli.xml</em> configuration file.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="color-output"><a class="anchor" href="#color-output"></a><a class="link" href="#color-output">3.2.9. Color output</a></h4>
<div class="paragraph">
<p>The CLI outputs results of commands and the prompt in color. To disable this, there are two possible ways to disable it:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>--no-color-output</em> will disable color output;</p>
</li>
<li>
<p>Change <em>&lt;enabled&gt;</em> to <code>false</code> in <code>jboss-cli.xml</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <em>&lt;color-output&gt;</em> block is  used to configure the  colors of the six basic elements that do support it</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Output messages: error, warning and success;</p>
</li>
<li>
<p>Required configuration options when using the auto-complete functionality;</p>
</li>
<li>
<p>The color of the default prompt;</p>
</li>
<li>
<p>The color of the prompt when using <code>batch</code> and any of the workflow commands, <code>if</code>, <code>for</code> and <code>try</code>.</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;color-output&gt;</span>
    <span class="tag">&lt;enabled&gt;</span>true<span class="tag">&lt;/enabled&gt;</span>
    <span class="tag">&lt;error-color&gt;</span>red<span class="tag">&lt;/error-color&gt;</span>
    <span class="tag">&lt;warn-color&gt;</span>yellow<span class="tag">&lt;/warn-color&gt;</span>
    <span class="tag">&lt;success-color&gt;</span>default<span class="tag">&lt;/success-color&gt;</span>
    <span class="tag">&lt;required-color&gt;</span>magenta<span class="tag">&lt;/required-color&gt;</span>
    <span class="tag">&lt;workflow-color&gt;</span>green<span class="tag">&lt;/workflow-color&gt;</span>
    <span class="tag">&lt;prompt-color&gt;</span>blue<span class="tag">&lt;/prompt-color&gt;</span>
<span class="tag">&lt;/color-output&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>There are eight available colors:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Black</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Magenta</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Blue</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Red</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Cyan</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">White</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Green</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Yellow</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>There is also the possibility of using the <em>default</em> color, which is the terminal&#8217;s configured foreground color.</p>
</div>
</div>
<div class="sect3">
<h4 id="paging-output"><a class="anchor" href="#paging-output"></a><a class="link" href="#paging-output">3.2.10. Paging and searching output</a></h4>
<div class="paragraph">
<p>In interactive mode, when the content to display is longer than the terminal
 height, the content is paged. You can navigate the content by using the following
 keys and mouse events:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>space or PAGE_DOWN: scroll the content one page down.</p>
</li>
<li>
<p>'\' or PAGE_UP: scroll the content one page up.</p>
</li>
<li>
<p>';' or up arrow or mouse wheel up: scroll the content one line up.</p>
</li>
<li>
<p>ENTER or down arrow or mouse wheel down: scroll the content one line down.</p>
</li>
<li>
<p>HOME or 'g': scroll to the top of the content. NB: HOME is only supported
for keyboards containing this key.</p>
</li>
<li>
<p>END or 'G': scroll to the bottom of the content. NB: END is only supported
for keyboards containing this key.</p>
</li>
<li>
<p>'q' or 'Q' or ESC: exit the paging.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>NB: When the end of the content is reached (using ENTER, space, &#8230;&#8203;) the paging
 is automatically exited.</p>
</div>
<div class="paragraph">
<p>It is possible to search for text when the content is paged. Search is operated
 with the following keys:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>'/' to display prompt allowing to type some text. Type return to launch the search.<br>
You can use up/down arrows to retrieve previously typed text. NB: search history
 is not persisted when CLI process exits.</p>
</li>
<li>
<p>'n' to jump to the next match if any. If no search text has been typed, then the
last entry from the search history is used.</p>
</li>
<li>
<p>'N' to jump to the previous match if any. If no search text has been typed,
then the last entry from the search history is used.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>There are two possible ways <strong>to disable</strong> the output paging and write the whole output of the commands at once:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>--no-output-paging</em> command line parameter will disable the output paging;</p>
</li>
<li>
<p>Add <em>&lt;output-paging&gt;false&lt;output-paging&gt;</em> in <code>jboss-cli.xml</code>.</p>
</li>
</ul>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
On Windows, searching and navigating backward is only supported starting with Windows 10 and Windows Server 2016.
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
If the CLI process is sent the signal KILL(9) while it is paging, the terminal will stay
 in alternate mode. This makes the terminal to behave in an unexpected manner (display and mouse events).
 In order to restore the terminal state call: <em>tput rmcup</em>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="batch-processing"><a class="anchor" href="#batch-processing"></a><a class="link" href="#batch-processing">3.2.11. Batch Processing</a></h4>
<div class="paragraph">
<p>The batch mode allows one to group commands and operations and execute
them together as an atomic unit. If at least one of the commands or
operations fails, all the other successfully executed commands and
operations in the batch are rolled back.</p>
</div>
<div class="paragraph">
<p>Not all of the commands are allowed in the batch. For example, commands
like <em>cd</em>, <em>ls</em>, <em>help</em>, etc. are not allowed in the batch since they
don&#8217;t translate into operation requests. Only the commands that
translate into operation requests are allowed in the batch. The batch,
actually, is executed as a composite operation request.</p>
</div>
<div class="paragraph">
<p>The batch mode is entered by executing command <em>batch</em>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[standalone@localhost:9990 /] batch
[standalone@localhost:9990 / #] /subsystem=datasources/data-source="java\:\/H2DS":enable
[standalone@localhost:9990 / #] /subsystem=messaging-activemq/server=default/jms-queue=newQueue:add</pre>
</div>
</div>
<div class="paragraph">
<p>You can execute a batch using the <em>run-batch</em> command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 / #] run-batch
The batch executed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>Exit the batch edit mode without losing your changes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 / #] holdback-batch
[standalone@localhost:9990 /]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then activate it later on again:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] batch
Re-activated batch
#1 /subsystem=datasources/data-source=java:/H2DS:\/H2DS:enable</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are several other notable batch commands available as well (tab
complete to see the list):</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>clear-batch</em></p>
</li>
<li>
<p><em>edit-batch-line</em> (e.g. <em>edit-batch line 3 create-jms-topic
name=mytopic</em>)</p>
</li>
<li>
<p><em>remove-batch-line</em> (e.g. <em>remove-batch-line 3</em>)</p>
</li>
<li>
<p><em>move-batch-line</em> (e.g. <em>move-batch-line 3 1</em>)</p>
</li>
<li>
<p><em>discard-batch</em></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="operators"><a class="anchor" href="#operators"></a><a class="link" href="#operators">3.2.12. Operators</a></h4>
<div class="paragraph">
<p>CLI has some operators that are similar to shell operators:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>&gt;</em> To redirect the output of a command/operation to a file:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre>:read-resource &gt; my-file.txt</pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><em>&gt;&gt;</em> To redirect the output of a command/operation and append it at the end of a file:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre>:read-resource &gt;&gt; my-file.txt</pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><em>|</em> To redirect the output of a command/operation to the <em>grep</em> command:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre>:read-resource | grep undefined</pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Default_HTTP_Interface_Security"><a class="anchor" href="#Default_HTTP_Interface_Security"></a><a class="link" href="#Default_HTTP_Interface_Security">3.3. Default HTTP Interface Security</a></h3>
<div class="paragraph">
<p>WildFly is distributed secured by default. The default security
mechanism is username / password based making use of HTTP Digest for the
authentication process.</p>
</div>
<div class="paragraph">
<p>The reason for securing the server by default is so that if the
management interfaces are accidentally exposed on a public IP address
authentication is required to connect - for this reason there is no
default user in the distribution.</p>
</div>
<div class="paragraph">
<p>The user are stored in a properties file called mgmt-users.properties
under standalone/configuration and domain/configuration depending on the
running mode of the server, these files contain the users username along
with a pre-prepared hash of the username along with the name of the
realm and the users password.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Although the properties files do not contain the plain text passwords
they should still be guarded as the pre-prepared hashes could be used to
gain access to any server with the same realm if the same user has used
the same password.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To manipulate the files and add users we provide a utility add-user.sh
and add-user.bat to add the users and generate the hashes, to add a user
you should execute the script and follow the guided process.
<span class="image"><img src="add-user.png" alt="images/add-user.png"></span><br>
The full details of the add-user utility are described later but for the
purpose of accessing the management interface you need to enter the
following values: -</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Type of user - This will be a 'Management User' to selection option a.</p>
</li>
<li>
<p>Realm - This MUST match the realm name used in the configuration so
unless you have changed the configuration to use a different realm name
leave this set as 'ManagementRealm'.</p>
</li>
<li>
<p>Username - The username of the user you are adding.</p>
</li>
<li>
<p>Password - The users password.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Provided the validation passes you will then be asked to confirm you
want to add the user and the properties files will be updated.</p>
</div>
<div class="paragraph">
<p>For the final question, as this is a user that is going to be accessing
the admin console just answer 'n' - this option will be described later
for adding secondary host controllers that authenticate against a
Domain Controller but that is a later topic.</p>
</div>
<div class="paragraph">
<p>After a new user has been added the server should be restarted or the
<code>load</code> operation should be executed on the <code>ManagementRealm</code> or
<code>ApplicationRealm</code> resource in the <code>elytron</code> subsystem as appropriate.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>[standalone@localhost:9990 /] /subsystem=elytron/properties-realm=ManagementRealm:load
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Default_Native_Interface_Security"><a class="anchor" href="#Default_Native_Interface_Security"></a><a class="link" href="#Default_Native_Interface_Security">3.4. Default Native Interface Security</a></h3>
<div class="paragraph">
<p>The native interface shares the same security configuration as the http
interface, however we also support a local authentication mechanism
which means that the CLI can authenticate against the local WildFly
instance without prompting the user for a username and password. This
mechanism only works if the user running the CLI has read access to the
standalone/tmp/auth folder or domain/tmp/auth folder under the
respective WildFly installation - if the local mechanism fails then the
CLI will fallback to prompting for a username and password for a user
configured as in <a href="#Default_HTTP_Interface_Security">Default HTTP Interface Security</a>.</p>
</div>
<div class="paragraph">
<p>Establishing a CLI connection to a remote server will require a username
and password by default.</p>
</div>
</div>
<div class="sect2">
<h3 id="command-line-interface"><a class="anchor" href="#command-line-interface"></a><a class="link" href="#command-line-interface">3.5. Command Line Interface</a></h3>
<div class="paragraph">
<p>The Command Line Interface (CLI) is a management tool for a managed
domain or standalone server. It allows a user to connect to the domain
controller or a standalone server and execute management operations
available through the de-typed management model.</p>
</div>
<div class="paragraph">
<p>Details on how to use the CLI can be found in the
<a href="#Command_Line_Interface">Command Line Interface page</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="configuration-files"><a class="anchor" href="#configuration-files"></a><a class="link" href="#configuration-files">3.6. Configuration Files</a></h3>
<div class="paragraph">
<p>WildFly stores its configuration in centralized XML configuration files,
one per server for standalone servers and, for managed domains, one per
host with an additional domain wide policy controlled by the Domain Controller.
These files are meant to be human-readable and human editable.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The XML configuration files act as a central, authoritative source of
configuration. Any configuration changes made via the web interface or
the CLI are persisted back to the XML configuration files. If a domain
or standalone server is offline, the XML configuration files can be hand
edited as well, and any changes will be picked up when the domain or
standalone server is next started. However, users are encouraged to use
the web interface or the CLI in preference to making offline edits to
the configuration files. External changes made to the configuration
files while processes are running will not be detected, and may be
overwritten.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="standalone-server-configuration-file"><a class="anchor" href="#standalone-server-configuration-file"></a><a class="link" href="#standalone-server-configuration-file">3.6.1. Standalone Server Configuration File</a></h4>
<div class="paragraph">
<p>The XML configuration for a standalone server can be found in the
<code>standalone/configuration</code> directory. The default configuration file is
<code>standalone/configuration/standalone.xml</code>.</p>
</div>
<div class="paragraph">
<p>The <code>standalone/configuration</code> directory includes a number of other
standard configuration files, e.g. <code>standalone-full.xml</code>,
<code>standalone-ha.xml</code> and <code>standalone-full-ha.xml</code> each of which is
similar to the default <code>standalone.xml</code> file but includes additional
subsystems not present in the default configuration. If you prefer to
use one of these files as your server configuration, you can specify it
with the <em>[line-through]*c*</em> or <em>-server-config</em> command line argument:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>bin/standalone.sh -c=standalone-full.xml</code></p>
</li>
<li>
<p><code>bin/standalone.sh --server-config=standalone-ha.xml</code></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="managed-domain-configuration-files"><a class="anchor" href="#managed-domain-configuration-files"></a><a class="link" href="#managed-domain-configuration-files">3.6.2. Managed Domain Configuration Files</a></h4>
<div class="paragraph">
<p>In a managed domain, the XML files are found in the
<code>domain/configuration</code> directory. There are two types of configuration
files – one per host, and then a single domain-wide file managed by the
primary Host Controller, aka the Domain Controller. (For more on the types of
processes in a managed domain, see <a href="#Operating_modes">Operating
Modes</a>.)</p>
</div>
<div class="sect4">
<h5 id="host-specific-configuration-host.xml"><a class="anchor" href="#host-specific-configuration-host.xml"></a><a class="link" href="#host-specific-configuration-host.xml">Host Specific Configuration – host.xml</a></h5>
<div class="paragraph">
<p>When you start a managed domain process, a Host Controller instance is
launched, and it parses its own configuration file to determine its own
configuration, how it should integrate with the rest of the domain, any
host-specific values for settings in the domain wide configuration (e.g.
IP addresses) and what servers it should launch. This information is
contained in the host-specific configuration file, the default version
of which is <code>domain/configuration/host.xml</code>.</p>
</div>
<div class="paragraph">
<p>Each host will have its own variant <code>host.xml</code>, with settings
appropriate for its role in the domain. WildFly ships with three
standard variants:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">host-primary.xml</th>
<th class="tableblock halign-left valign-top">A configuration that specifies the Host Controller
should become the primary Host Controller, aka the Domain Controller.
No servers will be started by this Host Controller, which is a recommended
setup for a production Domain Controller.</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host-secondary.xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A configuration that specifies the Host Controller
should not become the primary Host Controller and instead should register with a remote
primary Host Controller and be controlled by it. This configuration launches servers,
although a user will likely wish to modify how many servers are launched
and what server groups they belong to.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host.xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The default host configuration, tailored for an easy out of
the box experience experimenting with a managed domain. This
configuration specifies the Host Controller should become the primary Host Controller,
aka the Domain Controller, but it also launches a couple of servers.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Which host-specific configuration should be used can be controlled via
the _ <em>--host-config_</em> command line argument:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ bin/domain.sh --host-config=host-primary.xml</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="domain-wide-configuration-domain.xml"><a class="anchor" href="#domain-wide-configuration-domain.xml"></a><a class="link" href="#domain-wide-configuration-domain.xml">Domain Wide Configuration – domain.xml</a></h5>
<div class="paragraph">
<p>Once a Host Controller has processed its host-specific configuration, it
knows whether it is configured to act as the Domain Controller.
If it is, it must parse the domain wide configuration file, by default
located at <code>domain/configuration/domain.xml</code>. This file contains the
bulk of the settings that should be applied to the servers in the domain
when they are launched – among other things, what subsystems they should
run with what settings, what sockets should be used, and what
deployments should be deployed.</p>
</div>
<div class="paragraph">
<p>Which domain-wide configuration should be used can be controlled via the
_ <em>--domain-config_</em> command line argument:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ bin/domain.sh --domain-config=domain-production.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>That argument is only relevant for hosts configured to act as the
Domain Controller.</p>
</div>
<div class="paragraph">
<p>A secondary Host Controller does not usually parse the domain wide
configuration file. A secondary Host Controller gets the domain wide configuration from the
remote Domain Controller when it registers with it. A secondary Host Controller also
will not persist changes to a <code>domain.xml</code> file if one is present on the
filesystem. For that reason it is recommended that no <code>domain.xml</code> be
kept on the filesystem of hosts that will only run as secondary Host Controllers.</p>
</div>
<div class="paragraph">
<p>A secondary Host Controller can be configured to keep a locally persisted copy of the domain
wide configuration and then use it on boot (in case the Domain Controller is not
available.) See <em>--backup and --cached-dc</em> under
<a href="#Command_line_parameters">Command line parameters</a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Interfaces_and_ports"><a class="anchor" href="#Interfaces_and_ports"></a><a class="link" href="#Interfaces_and_ports">4. Interfaces and ports</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="interface-declarations"><a class="anchor" href="#interface-declarations"></a><a class="link" href="#interface-declarations">4.1. Interface declarations</a></h3>
<div class="paragraph">
<p>WildFly uses named interface references throughout the configuration. A
network interface is declared by specifying a logical name and a
selection criteria for the physical interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :read-children-names(child-type=interface)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [
       &quot;management&quot;,
       &quot;public&quot;
   ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This means the server in question declares two interfaces: One is
referred to as " <em>management</em>"; the other one " <em>public</em>". The "
<em>management</em>" interface is used for all components and services that are
required by the management layer (i.e. the HTTP Management Endpoint).
The " <em>public</em>" interface binding is used for any application related
network communication (i.e. Web, Messaging, etc). There is nothing
special about these names; interfaces can be declared with any name.
Other sections of the configuration can then reference those interfaces
by their logical name, rather than having to include the full details of
the interface (which, on servers in a management domain, may vary on
different machines).</p>
</div>
<div class="paragraph">
<p>The <code>domain.xml</code>, <code>host.xml</code> and <code>standalone.xml</code> configuration files
all include a section where interfaces can be declared. If we take a
look at the XML declaration it reveals the selection criteria. The
criteria is one of two types: either a single element indicating that
the interface should be bound to a wildcard address, or a set of one or
more characteristics that an interface or address must have in order to
be a valid match. The selection criteria in this example are specific IP
addresses for each interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interfaces&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
<span class="tag">&lt;/interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Some other examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">global</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="comment">&lt;!-- Use the wildcard address --&gt;</span>
   <span class="tag">&lt;any-address</span><span class="tag">/&gt;</span>
<span class="tag">&lt;/interface&gt;</span>
 
<span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">external</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;nic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">eth0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/interface&gt;</span>
 
<span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="comment">&lt;!-- Match any interface/address on the right subnet if it's
        up, supports multicast and isn't point-to-point --&gt;</span>
   <span class="tag">&lt;subnet-match</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">192.168.0.0/16</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;up</span><span class="tag">/&gt;</span>
   <span class="tag">&lt;multicast</span><span class="tag">/&gt;</span>
   <span class="tag">&lt;not&gt;</span>
      <span class="tag">&lt;point-to-point</span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/not&gt;</span>
<span class="tag">&lt;/interface&gt;</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
An interface configuration element is used to provide a single <code>InetAddress</code> to parts
of the server that reference that interface. If the selection criteria specified for
the interface element results in more than one address meeting the criteria, then a
warning will be logged and one just one address will be selected and used. Preference
will be given to network interfaces that are up, are non-loopback and are not
point-to-point.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="the-b-command-line-argument"><a class="anchor" href="#the-b-command-line-argument"></a><a class="link" href="#the-b-command-line-argument">4.1.1. The -b command line argument</a></h4>
<div class="paragraph">
<p>WildFly supports using the <code>-b</code> command line argument to specify the
address to assign to interfaces. See
<a href="#controlling-the-bind-address">Controlling the Bind Address with -b</a> for further details.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="socket-binding-groups"><a class="anchor" href="#socket-binding-groups"></a><a class="link" href="#socket-binding-groups">4.2. Socket Binding Groups</a></h3>
<div class="paragraph">
<p>The socket configuration in WildFly works similarly to the interfaces
declarations. Sockets are declared using a logical name, by which they
will be referenced throughout the configuration. Socket declarations are
grouped under a certain name. This allows you to easily reference a
particular socket binding group when configuring server groups in a
managed domain. Socket binding groups reference an interface by its
logical name:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.management.http.port:9990}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-https</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.management.https.port:9993}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ajp</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.ajp.port:8009}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.http.port:8080}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">https</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.https.port:8443}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-recovery-environment</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">4712</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-status-manager</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">4713</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/socket-binding-group&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>A socket binding includes the following information:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>name&#8201;&#8212;&#8201;logical name of the socket configuration that should be used
elsewhere in the configuration</p>
</li>
<li>
<p>port&#8201;&#8212;&#8201;base port to which a socket based on this configuration should
be bound. (Note that servers can be configured to override this base
value by applying an increment or decrement to all port values.)</p>
</li>
<li>
<p>interface (optional)&#8201;&#8212;&#8201;logical name (see "Interfaces declarations"
above) of the interface to which a socket based on this configuration
should be bound. If not defined, the value of the "default-interface"
attribute from the enclosing socket binding group will be used.</p>
</li>
<li>
<p>multicast-address (optional)&#8201;&#8212;&#8201;if the socket will be used for
multicast, the multicast address to use</p>
</li>
<li>
<p>multicast-port (optional)&#8201;&#8212;&#8201;if the socket will be used for multicast,
the multicast port to use</p>
</li>
<li>
<p>fixed-port (optional, defaults to false)&#8201;&#8212;&#8201;if true, declares that the
value of port should always be used for the socket and should not be
overridden by applying an increment or decrement</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="ipv4-versus-ipv6"><a class="anchor" href="#ipv4-versus-ipv6"></a><a class="link" href="#ipv4-versus-ipv6">4.3. IPv4 versus IPv6</a></h3>
<div class="paragraph">
<p>WildFly supports the use of both IPv4 and IPv6 addresses. By default,
WildFly is configured for use in an IPv4 network and so if you are
running in an IPv4 network, no changes are required. If you need to run
in an IPv6 network, the changes required are minimal and involve
changing the JVM stack and address preferences, and adjusting any
interface IP address values specified in the configuration
(standalone.xml or domain.xml).</p>
</div>
<div class="sect3">
<h4 id="stack-and-address-preference"><a class="anchor" href="#stack-and-address-preference"></a><a class="link" href="#stack-and-address-preference">4.3.1. Stack and address preference</a></h4>
<div class="paragraph">
<p>The system properties java.net.preferIPv4Stack and
java.net.preferIPv6Addresses are used to configure the JVM for use with
IPv4 or IPv6 addresses. With WildFly, in order to run using IPv4
addresses, you need to specify java.net.preferIPv4Stack=true; in order
to run with IPv6 addresses, you need to specify
java.net.preferIPv4Stack=false (the JVM default) and
java.net.preferIPv6Addresses=true. The latter ensures that any hostname
to IP address conversions always return IPv6 address variants.</p>
</div>
<div class="paragraph">
<p>These system properties are conveniently set by the JAVA_OPTS
environment variable, defined in the standalone.conf (or domain.conf)
file. For example, to change the IP stack preference from its default of
IPv4 to IPv6, edit the standalone.conf (or domain.conf) file and change
its default IPv4 setting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=true ..."
...</pre>
</div>
</div>
<div class="paragraph">
<p>to an IPv6 suitable setting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true ..."
...</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="ip-address-literals"><a class="anchor" href="#ip-address-literals"></a><a class="link" href="#ip-address-literals">4.3.2. IP address literals</a></h4>
<div class="paragraph">
<p>To change the IP address literals referenced in standalone.xml (or
domain.xml), first visit the interface declarations and ensure that
valid IPv6 addresses are being used as interface values. For example, to
change the default configuration in which the loopback interface is used
as the primary interface, change from the IPv4 loopback address:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interfaces&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address.management:127.0.0.1}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address:127.0.0.1}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
<span class="tag">&lt;/interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>to the IPv6 loopback address:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interfaces&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address.management:[::1]}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
  <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address:[::1]}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/interface&gt;</span>
<span class="tag">&lt;/interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that when embedding IPv6 address literals in the substitution
expression, square brackets surrounding the IP address literal are used
to avoid ambiguity. This follows the convention for the use of IPv6
literals in URLs.</p>
</div>
<div class="paragraph">
<p>Over and above making such changes for the interface definitions, you
should also check the rest of your configuration file and adjust IP
address literals from IPv4 to IPv6 as required.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="administrative-security"><a class="anchor" href="#administrative-security"></a><a class="link" href="#administrative-security">5. Administrative security</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="add-user-utility"><a class="anchor" href="#add-user-utility"></a><a class="link" href="#add-user-utility">5.1. add-user utility</a></h3>
<div class="paragraph">
<p>For use with the default configuration we supply a utility <code>add-user</code>
which can be used to manage the properties files for the default realms
used to store the users and their roles.</p>
</div>
<div class="paragraph">
<p>The add-user utility can be used to manage both the users in the
<code>ManagementRealm</code> and the users in the <code>ApplicationRealm</code>, changes made
apply to the properties file used both for domain mode and standalone
mode.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
After you have installed your application server and decided if you are
going to run in standalone mode or domain mode you can delete the parent
folder for the mode you are not using, the add-user utility will then
only be managing the properties file for the mode in use.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The add-user utility is a command line utility however it can be run in
both interactive and non-interactive mode. Depending on your platform
the script to run the add-user utility is either <code>add-user.sh</code> or
<code>add-user.bat</code> which can be found in \{ <code>jboss.home}/bin</code>.</p>
</div>
<div class="paragraph">
<p>This guide now contains a couple of examples of this utility in use to
accomplish the most common tasks.</p>
</div>
<div class="sect3">
<h4 id="adding-a-user"><a class="anchor" href="#adding-a-user"></a><a class="link" href="#adding-a-user">5.1.1. Adding a User</a></h4>
<div class="paragraph">
<p>Adding users to the properties files is the primary purpose of this
utility. Usernames can only contain the following characters in any
number and in any order:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Alphanumeric characters (a-z, A-Z, 0-9)</p>
</li>
<li>
<p>Dashes (-), periods (.), commas (,), at (@)</p>
</li>
<li>
<p>Escaped backslash ( \\ )</p>
</li>
<li>
<p>Escaped equals (\=)</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="a-management-user"><a class="anchor" href="#a-management-user"></a><a class="link" href="#a-management-user">A Management User</a></h5>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The default name of the realm for management users is <code>ManagementRealm</code>,
when the utility prompts for the realm name just accept the default
unless you have switched to a different realm.
</td>
</tr>
</table>
</div>
<div class="sect5">
<h6 id="interactive-mode"><a class="anchor" href="#interactive-mode"></a><a class="link" href="#interactive-mode">Interactive Mode</a></h6>
<div class="paragraph">
<p><span class="image"><img src="add-mgmt-user-interactive.png" alt="images/add-mgmt-user-interactive.png"></span></p>
</div>
<div class="paragraph">
<p>Here we have added a new Management User called <code>adminUser</code>, as you can
see some of the questions offer default responses so you can just press
enter without repeating the default value.</p>
</div>
<div class="paragraph">
<p>For now just answer <code>n</code> or <code>no</code> to the final question, adding users to
be used by processes is described in more detail in the domain
management chapter.</p>
</div>
</div>
<div class="sect5">
<h6 id="add-user-non-interactive-mode"><a class="anchor" href="#add-user-non-interactive-mode"></a><a class="link" href="#add-user-non-interactive-mode">Non-Interactive Mode</a></h6>
<div class="paragraph">
<p>To add a user in non-interactive mode the command
<code>./add-user.sh {username} {password</code>} can be used.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="add-mgmt-user-non-interactive.png" alt="images/add-mgmt-user-non-interactive.png"></span></p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
If you add users using this approach there is a risk that any other user
that can view the list of running process may see the arguments
including the password of the user being added, there is also the risk
that the username / password combination will be cached in the history
file of the shell you are currently using.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect4">
<h5 id="an-application-user"><a class="anchor" href="#an-application-user"></a><a class="link" href="#an-application-user">An Application User</a></h5>
<div class="paragraph">
<p>When adding application users in addition to adding the user with their
pre-hashed password it is also now possible to define the roles of the
user.</p>
</div>
<div class="sect5">
<h6 id="interactive-mode-1"><a class="anchor" href="#interactive-mode-1"></a><a class="link" href="#interactive-mode-1">Interactive Mode</a></h6>
<div class="paragraph">
<p><span class="image"><img src="add-app-user-interactive.png" alt="images/add-app-user-interactive.png"></span></p>
</div>
<div class="paragraph">
<p>Here a new user called <code>appUser</code> has been added, in this case a comma
separated list of roles has also been specified.</p>
</div>
<div class="paragraph">
<p>As with adding a management user just answer <code>n</code> or <code>no</code> to the final
question until you know you are adding a user that will be establishing
a connection from one server to another.</p>
</div>
</div>
<div class="sect5">
<h6 id="non-interactive-mode-1"><a class="anchor" href="#non-interactive-mode-1"></a><a class="link" href="#non-interactive-mode-1">Non-Interactive Mode</a></h6>
<div class="paragraph">
<p>To add an application user non-interactively use the command
<code>./add-user.sh -a {username} {password</code>}.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="add-app-user-non-interactive.png" alt="images/add-app-user-non-interactive.png"></span></p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Non-interactive mode does not support defining a list of users, to
associate a user with a set of roles you will need to manually edit the
<code>application-roles.properties</code> file by hand.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="updating-a-user"><a class="anchor" href="#updating-a-user"></a><a class="link" href="#updating-a-user">5.1.2. Updating a User</a></h4>
<div class="paragraph">
<p>Within the add-user utility it is also possible to update existing
users, in interactive mode you will be prompted to confirm if this is
your intention.</p>
</div>
<div class="sect4">
<h5 id="a-management-user-1"><a class="anchor" href="#a-management-user-1"></a><a class="link" href="#a-management-user-1">A Management User</a></h5>
<div class="sect5">
<h6 id="interactive-mode-2"><a class="anchor" href="#interactive-mode-2"></a><a class="link" href="#interactive-mode-2">Interactive Mode</a></h6>
<div class="paragraph">
<p><span class="image"><img src="update-mgmt-user-interactive.png" alt="images/update-mgmt-user-interactive.png"></span></p>
</div>
</div>
<div class="sect5">
<h6 id="non-interactive-mode-2"><a class="anchor" href="#non-interactive-mode-2"></a><a class="link" href="#non-interactive-mode-2">Non-Interactive Mode</a></h6>
<div class="paragraph">
<p>In non-interactive mode if a user already exists the update is automatic
with no confirmation prompt.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="an-application-user-1"><a class="anchor" href="#an-application-user-1"></a><a class="link" href="#an-application-user-1">An Application User</a></h5>
<div class="sect5">
<h6 id="interactive-mode-3"><a class="anchor" href="#interactive-mode-3"></a><a class="link" href="#interactive-mode-3">Interactive Mode</a></h6>
<div class="paragraph">
<p><span class="image"><img src="update-app-user-interactive.png" alt="images/update-app-user-interactive.png"></span></p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
On updating a user with roles you will need to re-enter the list of
roles assigned to the user.
</td>
</tr>
</table>
</div>
</div>
<div class="sect5">
<h6 id="non-interactive-mode"><a class="anchor" href="#non-interactive-mode"></a><a class="link" href="#non-interactive-mode">Non-Interactive Mode</a></h6>
<div class="paragraph">
<p>In non-interactive mode if a user already exists the update is automatic
with no confirmation prompt.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="community-contributions"><a class="anchor" href="#community-contributions"></a><a class="link" href="#community-contributions">5.1.3. Community Contributions</a></h4>
<div class="paragraph">
<p>There are still a few features to add to the add-user utility such as
removing users or adding application users with roles in non-interactive
mode, if you are interested in contributing to WildFly development the
add-user utility is a good place to start as it is a stand alone
utility, however it is a part of the AS build so you can become familiar
with the AS development processes without needing to delve straight into
the internals of the application server.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="RBAC"><a class="anchor" href="#RBAC"></a><a class="link" href="#RBAC">5.2. Authorizing management actions with Role Based Access Control</a></h3>
<div class="paragraph">
<p>WildFly introduces a Role Based Access Control scheme that allows
different administrative users to have different sets of permissions to
read and update parts of the management tree. This replaces the simple
permission scheme used in JBoss AS 7, where anyone who could
successfully authenticate to the management security realm would have
all permissions.</p>
</div>
<div class="sect3">
<h4 id="access-control-providers"><a class="anchor" href="#access-control-providers"></a><a class="link" href="#access-control-providers">5.2.1. Access Control Providers</a></h4>
<div class="paragraph">
<p>WildFly ships with two access control "providers", the "simple"
provider, and the "rbac" provider. The "simple" provider is the default,
and provides a permission scheme equivalent to the JBoss AS 7 behavior
where any authenticated administrator has all permissions. The "rbac"
provider gives the finer grained permission scheme that is the focus of
this section.</p>
</div>
<div class="paragraph">
<p>The access control configuration is included in the management section
of a standalone server&#8217;s standalone.xml, or in a new "management"
section in a managed domain&#8217;s domain.xml. The access control policy is
centrally configured in a managed domain.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;management&gt;</span>
    . . .
    <span class="tag">&lt;access-control</span> <span class="attribute-name">provider</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;role-mapping&gt;</span>
            <span class="tag">&lt;role</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SuperUser</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;include&gt;</span>
                    <span class="tag">&lt;user</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">$local</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
                <span class="tag">&lt;/include&gt;</span>
            <span class="tag">&lt;/role&gt;</span>
        <span class="tag">&lt;/role-mapping&gt;</span>
    <span class="tag">&lt;/access-control&gt;</span>
<span class="tag">&lt;/management&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, the provider is set to "simple" by default. With the
"simple" provider, the nested "role-mapping" section is not actually
relevant. It&#8217;s there to help ensure that if the provider attribute is
switched to "rbac" there will be at least one user mapped to a role that
can continue to administer the system. This default mapping assigns the
"$local" user name to the RBAC role that provides all permissions, the
"SuperUser" role. The "$local" user name is the name an administrator
will be assigned if he or she uses the CLI on the same system as the
WildFly instance and the "local" authentication scheme is enabled.</p>
</div>
</div>
<div class="sect3">
<h4 id="rbac-provider-overview"><a class="anchor" href="#rbac-provider-overview"></a><a class="link" href="#rbac-provider-overview">5.2.2. RBAC provider overview</a></h4>
<div class="paragraph">
<p>The access control scheme implemented by the "rbac" provider is based on
seven standard roles. A role is a named set of permissions to perform
one of the actions: addressing (i.e. looking up) a management resource,
reading it, or modifying it. The different roles have constraints
applied to their permissions that are used to determine whether the
permission is granted.</p>
</div>
<div class="sect4">
<h5 id="rbac-roles"><a class="anchor" href="#rbac-roles"></a><a class="link" href="#rbac-roles">RBAC roles</a></h5>
<div class="paragraph">
<p>The seven standard roles are divided into two broad categories, based on
whether the role can deal with items that are considered to be "security
sensitive". Resources, attributes and operations that may affect
administrative security (e.g. security realm resources and attributes
that contain passwords) are "security sensitive".</p>
</div>
<div class="paragraph">
<p>Four roles are not given permissions for "security sensitive" items:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Monitor – a read-only role. Cannot modify any resource.</p>
</li>
<li>
<p>Operator – Monitor permissions, plus can modify runtime state, but
cannot modify anything that ends up in the persistent configuration.
Could, for example, restart a server.</p>
</li>
<li>
<p>Maintainer – Operator permissions, plus can modify the persistent
configuration.</p>
</li>
<li>
<p>Deployer – like a Maintainer, but with permission to modify persistent
configuration constrained to resources that are considered to be
"application resources". A deployment is an application resource. The
messaging server is not. Items like datasources and Jakarta Messaging destinations are
not considered to be application resources by default, but this is
<a href="#application-constraint">configurable</a>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Three roles are granted permissions for security sensitive items:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>SuperUser – has all permissions. Equivalent to a JBoss AS 7
administrator.</p>
</li>
<li>
<p>Administrator – has all permissions except cannot read or write
resources related to the administrative audit logging system.</p>
</li>
<li>
<p>Auditor – can read anything. Can only modify the resources related to
the administrative audit logging system.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The Auditor and Administrator roles are meant for organizations that
want a separation of responsibilities between those who audit normal
administrative actions and those who perform them, with those who
perform most actions (Administrator role) not being able to read or
alter the auditing configuration.</p>
</div>
</div>
<div class="sect4">
<h5 id="access-control-constraints"><a class="anchor" href="#access-control-constraints"></a><a class="link" href="#access-control-constraints">Access control constraints</a></h5>
<div class="paragraph">
<p>The following factors are used to determine whether a given role is
granted a permission:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>What the requested action is (address, read, write)</p>
</li>
<li>
<p>Whether the resource, attribute or operation affects the persistent
configuration</p>
</li>
<li>
<p>Whether the resource, attribute or operation is related to the
administrative audit logging function</p>
</li>
<li>
<p>Whether the resource, attribute or operation is configured as security
sensitive</p>
</li>
<li>
<p>Whether an attribute or operation parameter value has a security vault
expression</p>
</li>
<li>
<p>Whether a resource is considered to be associated with applications,
as opposed to being part of a general container configuration</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The first three of these factors are non-configurable; the latter three
allow some customization. See "
<a href="#configuring-constraints">Configuring constraints</a>"
for details.</p>
</div>
</div>
<div class="sect4">
<h5 id="addressing-a-resource"><a class="anchor" href="#addressing-a-resource"></a><a class="link" href="#addressing-a-resource">Addressing a resource</a></h5>
<div class="paragraph">
<p>As mentioned above, permissions are granted to perform one of three
actions, addressing a resource, reading it, and modifying. The latter
two actions are fairly self-explanatory. But what is meant by
"addressing" a resource?</p>
</div>
<div class="paragraph">
<p>"Addressing" a resource refers to taking an action that allows the user
to determine whether a resource at a given address actually exists. For
example, the "read-children-names" operation lets a user determine valid
addresses. Trying to read a resource and getting a "Permission denied"
error also gives the user a clue that there actually is a resource at
the requested address.</p>
</div>
<div class="paragraph">
<p>Some resources may include sensitive information as part of their
address. For example, security realm resources include the realm name as
the last element in the address. That realm name is potentially security
sensitive; for example it is part of the data used when creating a hash
of a user password. Because some addresses may contain security
sensitive data, a user needs permission to even "address" a resource. If
a user attempts to address a resource and does not have permission, they
will not receive a "permission denied" type error. Rather, the system
will respond as if the resource does not even exist, e.g. excluding the
resource from the result of the "read-children-names" operation or
responding with a "No such resource" error instead of "Permission
denied" if the user is attempting to read or write the resource.</p>
</div>
<div class="paragraph">
<p>Another term for "addressing" a resource is "looking up" the resource.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="switching-to-the-rbac-provider"><a class="anchor" href="#switching-to-the-rbac-provider"></a><a class="link" href="#switching-to-the-rbac-provider">5.2.3. Switching to the "rbac" provider</a></h4>
<div class="paragraph">
<p>Use the CLI to switch the access-control provider.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Before changing the provider to "rbac", be sure your configuration has a
user who will be mapped to one of the RBAC roles, preferably with at
least one in the Administrator or SuperUser role. Otherwise your
installation will not be manageable except by shutting it down and
editing the xml configuration. If you have started with one of the
standard xml configurations shipped with WildFly, the "$local" user will
be mapped to the "SuperUser" role and the "local" authentication scheme will be
enabled. This will allow a user running the CLI on the same system as the
WildFly process to have full administrative permissions. Remote CLI users and
web-based admin console users will have no permissions.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>We recommend <a href="#mapping-users-and-groups-to-roles">mapping at least one
user</a> besides "$local" before switching the provider to "rbac". You can
do all of the configuration associated with the "rbac" provider even
when the provider is set to "simple"</p>
</div>
<div class="paragraph">
<p>The management resources related to access control are located in the
<code>core-service=management/access=authorization</code> portion of the management
resource tree. Update the <code>provider</code> attribute to change between the
"simple" and "rbac" providers. Any update requires a reload or restart
to take effect.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] cd core-service=management/access=authorization
[standalone@localhost:9990 access=authorization] :write-attribute(name=provider,value=rbac)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}
[standalone@localhost:9990 access=authorization] reload</code></pre>
</div>
</div>
<div class="paragraph">
<p>In a managed domain, the access control configuration is part of the
domain wide configuration, so the resource address is the same as above,
but the CLI is connected to the Domain Controller:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] cd core-service=management/access=authorization
[domain@localhost:9990 access=authorization] :write-attribute(name=provider,value=rbac)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    },
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {
            &quot;outcome&quot; =&gt; &quot;success&quot;,
            &quot;response-headers&quot; =&gt; {
                &quot;operation-requires-reload&quot; =&gt; true,
                &quot;process-state&quot; =&gt; &quot;reload-required&quot;
            }
        }},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {
            &quot;outcome&quot; =&gt; &quot;success&quot;,
            &quot;response-headers&quot; =&gt; {
                &quot;operation-requires-reload&quot; =&gt; true,
                &quot;process-state&quot; =&gt; &quot;reload-required&quot;
            }
        }}
    }}}}
}
[domain@localhost:9990 access=authorization] reload --host=primary</code></pre>
</div>
</div>
<div class="paragraph">
<p>As with a standalone server, a reload or restart is required for the
change to take effect. In this case, all hosts and servers in the domain
will need to be reloaded or restarted, starting with the Domain
Controller, so be sure to plan well before making this change.</p>
</div>
</div>
<div class="sect3">
<h4 id="mapping-users-and-groups-to-roles"><a class="anchor" href="#mapping-users-and-groups-to-roles"></a><a class="link" href="#mapping-users-and-groups-to-roles">5.2.4. Mapping users and groups to roles</a></h4>
<div class="paragraph">
<p>Once the "rbac" access control provider is enabled, only users who are
mapped to one of the available roles will have any administrative
permissions at all. So, to make RBAC useful, a mapping between
individual users or groups of users and the available roles must be
performed.</p>
</div>
<div class="sect4">
<h5 id="mapping-individual-users"><a class="anchor" href="#mapping-individual-users"></a><a class="link" href="#mapping-individual-users">Mapping individual users</a></h5>
<div class="paragraph">
<p>The easiest way to map individual users to roles is to use the web-based
admin console.</p>
</div>
<div class="paragraph">
<p>Navigate to the "Administration" tab and the "Users" subtab. From there
individual user mappings can be added, removed, or edited.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="usermapping.png" alt="images/usermapping.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>The CLI can also be used to map individuals users to roles.</p>
</div>
<div class="paragraph">
<p>First, if one does not exist, create the parent resource for all
mappings for a role. Here we create the resource for the <code>Administrator</code>
role.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/role-mapping=Administrator:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once this is done, map a user to the role:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/role-mapping=Administrator/include=user-jsmith:add(name=jsmith,type=USER)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now if user <code>jsmith</code> authenticates to any security domain associated with
the management interface they are using, he will be mapped to the
<code>Administrator</code> role.</p>
</div>
</div>
<div class="sect4">
<h5 id="user-groups"><a class="anchor" href="#user-groups"></a><a class="link" href="#user-groups">User groups</a></h5>
<div class="paragraph">
<p>A "group" is an arbitrary collection of users that may exist in the end
user environment. They can be named whatever the end user organization
wants and can contain whatever users the end user organization wants.
Some of the authentication store types supported by WildFly security
realms include the ability to access information about what groups a
user is a member of and associate this information with the <code>Subject</code>
produced when the user is authenticated. This is currently supported for
the following authentication store types:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>properties file (via the <code>&lt;realm_name&gt;-groups.properties</code> file)</p>
</li>
<li>
<p>LDAP (via directory-server-specific configuration)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Groups are convenient when it comes to associating a user with a role,
since entire groups can be associated with a role in a single mapping.</p>
</div>
</div>
<div class="sect4">
<h5 id="mapping-groups-to-roles"><a class="anchor" href="#mapping-groups-to-roles"></a><a class="link" href="#mapping-groups-to-roles">Mapping groups to roles</a></h5>
<div class="paragraph">
<p>The easiest way to map groups to roles is to use the web-based admin
console.</p>
</div>
<div class="paragraph">
<p>Navigate to the "Administration" tab and the "Groups" subtab. From there
group mappings can be added, removed, or edited.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="groupmapping.png" alt="images/groupmapping.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>The CLI can also be used to map groups to roles. The only difference to
individual user mapping is the value of the <code>type</code> attribute should be
<code>GROUP</code> instead of <code>USER</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/role-mapping=Administrator/include=group-SeniorAdmins:add(name=SeniorAdmins,type=GROUP)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="including-all-authenticated-users-in-a-role"><a class="anchor" href="#including-all-authenticated-users-in-a-role"></a><a class="link" href="#including-all-authenticated-users-in-a-role">Including all authenticated users in a role</a></h5>
<div class="paragraph">
<p>It&#8217;s possible to specify that all authenticated users should be mapped
to a particular role. This could be used, for example, to ensure that
anyone who can authenticate can at least have <code>Monitor</code> privileges.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
A user who can authenticate to the management security realm but who
does not map to a role will not be able to perform any administrative
functions, not even reads.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In the web based admin console, navigate to the "Administration" tab,
"Roles" subtab, highlight the relevant role, click the "Edit" button and
click on the "Include All" checkbox:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="includeall.png" alt="images/includeall.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>The same change can be made using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/role-mapping=Monitor:write-attribute(name=include-all,value=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="excluding-users-and-groups"><a class="anchor" href="#excluding-users-and-groups"></a><a class="link" href="#excluding-users-and-groups">Excluding users and groups</a></h5>
<div class="paragraph">
<p>It is also possible to explicitly exclude certain users and groups from
a role. Exclusions take precedence over inclusions, including cases
where the <code>include-all</code> attribute is set to true for a role.</p>
</div>
<div class="paragraph">
<p>In the admin console, excludes are done in the same screens as includes.
In the add dialog, simply change the "Type" pulldown to "Exclude".</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="excludemapping.png" alt="images/excludemapping.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>In the CLI, excludes are identical to includes, except the resource
address has <code>exclude</code> instead of <code>include</code> as the key for the last
address element:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/role-mapping=Monitor/exclude=group-Temps:add(name=Temps,type=GROUP)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="users-who-map-to-multiple-roles"><a class="anchor" href="#users-who-map-to-multiple-roles"></a><a class="link" href="#users-who-map-to-multiple-roles">Users who map to multiple roles</a></h5>
<div class="paragraph">
<p>It is possible that a given user will be mapped to more than one role.
When this occurs, by default the user will be granted the union of the
permissions of the two roles. This behavior can be changed <strong>on a global
basis</strong> to instead respond to the user request with an error if this
situation is detected:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] cd core-service=management/access=authorization
[standalone@localhost:9990 access=authorization] :write-attribute(name=permission-combination-policy,value=rejecting)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that no reload is required; the change takes immediate effect.</p>
</div>
<div class="paragraph">
<p>To restore the default behavior, set the value to "permissive":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] cd core-service=management/access=authorization
[standalone@localhost:9990 access=authorization] :write-attribute(name=permission-combination-policy,value=permissive)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="adding-custom-roles-in-a-managed-domain"><a class="anchor" href="#adding-custom-roles-in-a-managed-domain"></a><a class="link" href="#adding-custom-roles-in-a-managed-domain">5.2.5. Adding custom roles in a managed domain</a></h4>
<div class="paragraph">
<p>A managed domain may involve a variety of servers running different
configurations and hosting different applications. In such an
environment, it is likely that there will be different teams of
administrators responsible for different parts of the domain. To allow
organizations to grant permissions to only parts of a domain, WildFly&#8217;s
RBAC scheme allows for the creation of custom "scoped roles". Scoped
roles are based on the seven standard roles, but with permissions
limited to a portion of the domain – either to a set of server groups or
to a set of hosts.</p>
</div>
<div class="sect4">
<h5 id="server-group-scoped-roles"><a class="anchor" href="#server-group-scoped-roles"></a><a class="link" href="#server-group-scoped-roles">Server group scoped roles</a></h5>
<div class="paragraph">
<p>The privileges for a server-group scoped role are constrained to
resources associated with one or more server groups. Server groups are
often associated with a particular application or set of applications;
organizations that have separate teams responsible for different
applications may find server-group scoped roles useful.</p>
</div>
<div class="paragraph">
<p>A server-group scoped role is equivalent to the default role upon which
it is based, but with privileges constrained to target resources in the
resource trees rooted in the server group resources. The server-group
scoped role can be configured to include privileges for the following
resources trees logically related to the server group:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Profile</p>
</li>
<li>
<p>Socket Binding Group</p>
</li>
<li>
<p>Deployment</p>
</li>
<li>
<p>Deployment override</p>
</li>
<li>
<p>Server group</p>
</li>
<li>
<p>Server config</p>
</li>
<li>
<p>Server</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Resources in the profile, socket binding group, server config and server
portions of the tree that are not logically related to a server group
associated with the server-group scoped role will not be addressable by
a user in that role. So, in a domain with server groups "a" and "b", a
user in a server-group scoped role that grants access to "a" will not be
able to address /server-group=b. The system will treat that resource as
non-existent for that user.</p>
</div>
<div class="paragraph">
<p>In addition to these privileges, users in a server-group scoped role
will have non-sensitive read privileges (equivalent to the Monitor role)
for resources other than those listed above.</p>
</div>
<div class="paragraph">
<p>The easiest way to create a server-group scoped role is to
<a href="#using-the-admin-console-to-create-scoped-roles">use the admin console</a>.
But you can also use the CLI to create a server-group scoped role.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/server-group-scoped-role=MainGroupAdmins:add(base-role=Administrator,server-groups=[main-server-group])
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once the role is created, users or groups can be mapped to it the same
as with the seven standard roles.</p>
</div>
</div>
<div class="sect4">
<h5 id="host-scoped-roles"><a class="anchor" href="#host-scoped-roles"></a><a class="link" href="#host-scoped-roles">Host scoped roles</a></h5>
<div class="paragraph">
<p>The privileges for a host-scoped role are constrained to resources
associated with one or more hosts. A user with a host-scoped role cannot
modify the domain wide configuration. Organizations may use host-scoped
roles to give administrators relatively broad administrative rights for
a host without granting such rights across the managed domain.</p>
</div>
<div class="paragraph">
<p>A host-scoped role is equivalent to the default role upon which it is
based, but with privileges constrained to target resources in the
resource trees rooted in the host resources for one or more specified
hosts.</p>
</div>
<div class="paragraph">
<p>In addition to these privileges, users in a host-scoped role will have
non-sensitive read privileges (equivalent to the Monitor role) for
domain wide resources (i.e. those not in the /host=* section of the
tree.)</p>
</div>
<div class="paragraph">
<p>Resources in the /host=* portion of the tree that are unrelated to the
hosts specified for the Host Scoped Role will not be visible to users in
that host-scoped role. So, in a domain with hosts "a" and "b", a user in
a host-scoped role that grants access to "a" will not be able to address
/host=b. The system will treat that resource as non-existent for that
user.</p>
</div>
<div class="paragraph">
<p>The easiest way to create a host-scoped role is to
<a href="#using-the-admin-console-to-create-scoped-roles">use the admin console</a>.
But you can also use the CLI to create a host scoped role.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /core-service=management/access=authorization/host-scoped-role=DCOperators:add(base-role=Operator,hosts=[primary]}
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once the role is created, users or groups can be mapped to it the same
as with the seven standard roles.</p>
</div>
</div>
<div class="sect4">
<h5 id="using-the-admin-console-to-create-scoped-roles"><a class="anchor" href="#using-the-admin-console-to-create-scoped-roles"></a><a class="link" href="#using-the-admin-console-to-create-scoped-roles">Using the admin console to create scoped roles</a></h5>
<div class="paragraph">
<p>Both server-group and host scoped roles can be added, removed or edited
via the admin console. Select "Scoped Roles" from the "Administration"
tab, "Roles" subtab:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="scopedroles.png" alt="images/scopedroles.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>When adding a new scoped role, use the dialogue&#8217;s "Type" pull down to
choose between a host scoped role and a server-group scoped role. Then
place the names of the relevant hosts or server groups in the "Scope"
text are.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="addscopedrole.png" alt="images/addscopedrole.png" width="450"></span></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-constraints"><a class="anchor" href="#configuring-constraints"></a><a class="link" href="#configuring-constraints">5.2.6. Configuring constraints</a></h4>
<div class="paragraph">
<p>The following factors are used to determine whether a given role is
granted a permission:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>What the requested action is (address, read, write)</p>
</li>
<li>
<p>Whether the resource, attribute or operation affects the persistent
configuration</p>
</li>
<li>
<p>Whether the resource, attribute or operation is related to the
administrative audit logging function</p>
</li>
<li>
<p>Whether the resource, attribute or operation is configured as security
sensitive</p>
</li>
<li>
<p>Whether an attribute or operation parameter value has a security vault
expression or an encrypted expression.</p>
</li>
<li>
<p>Whether a resource is considered to be associated with applications,
as opposed to being part of a general container configuration</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The first three of these factors are non-configurable; the latter three
allow some customization.</p>
</div>
<div class="sect4">
<h5 id="configuring-sensitivity"><a class="anchor" href="#configuring-sensitivity"></a><a class="link" href="#configuring-sensitivity">Configuring sensitivity</a></h5>
<div class="paragraph">
<p>"Sensitivity" constraints are about restricting access to
security-sensitive data. Different organizations may have different
opinions about what is security sensitive, so WildFly provides
configuration options to allow users to tailor these constraints.</p>
</div>
<div class="sect5">
<h6 id="sensitive-resources-attributes-and-operations"><a class="anchor" href="#sensitive-resources-attributes-and-operations"></a><a class="link" href="#sensitive-resources-attributes-and-operations">Sensitive resources, attributes and operations</a></h6>
<div class="paragraph">
<p>The developers of the WildFly core and of any subsystem may annotate
resources, attributes or operations with a "sensitivity classification".
Classifications are either provided by the core and may be applicable
anywhere in the management model, or they are scoped to a particular
subsystem. For each classification, there will be a setting declaring
whether by default the addressing, read and write actions are considered
to be sensitive. If an action is sensitive, only users in the roles able
to deal with sensitive data (Administrator, Auditor, SuperUser) will
have permissions.</p>
</div>
<div class="paragraph">
<p>Using the CLI, administrators can see the settings for a classification.
For example, there is a core classification called "socket-config" that
is applied to elements throughout the model that relate to configuring
sockets:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] cd core-service=management/access=authorization/constraint=sensitivity-classification/type=core/classification=socket-config
[domain@localhost:9990 classification=socket-config] ls -l
ATTRIBUTE                       VALUE     TYPE
configured-requires-addressable undefined BOOLEAN
configured-requires-read        undefined BOOLEAN
configured-requires-write       undefined BOOLEAN
default-requires-addressable    false     BOOLEAN
default-requires-read           false     BOOLEAN
default-requires-write          true      BOOLEAN
 
CHILD      MIN-OCCURS MAX-OCCURS
applies-to n/a        n/a</code></pre>
</div>
</div>
<div class="paragraph">
<p>The various <code>default-requires-&#8230;&#8203;</code> attributes indicate whether a user
must be in a role that allows security sensitive actions in order to
perform the action. In the <code>socket-config</code> example above,
<code>default-requires-write</code> is true, while the others are false. So, by
default modifying a setting involving socket configuration is considered
sensitive, while addressing those resources or doing reads is not
sensitive.</p>
</div>
<div class="paragraph">
<p>The <code>default-requires-&#8230;&#8203;</code> attributes are read-only. The
<code>configured-requires-&#8230;&#8203;</code> attributes however can be modified to override
the default settings with ones appropriate for your organization. For
example, if your organization doesn&#8217;t regard modifying socket
configuration settings to be security sensitive, you can change that
setting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 classification=socket-config] :write-attribute(name=configured-requires-write,value=false)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Administrators can also read the management model to see to which
resources, attributes and operations a particular sensitivity
classification applies:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 classification=socket-config] :read-children-resources(child-type=applies-to)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;/host=primary&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary&quot;,
            &quot;attributes&quot; =&gt; [],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; [&quot;resolve-internet-address&quot;]
        },
        &quot;/host=primary/core-service=host-environment&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary/core-service=host-environment&quot;,
            &quot;attributes&quot; =&gt; [
                &quot;host-controller-port&quot;,
                &quot;host-controller-address&quot;,
                &quot;process-controller-port&quot;,
                &quot;process-controller-address&quot;
            ],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/host=primary/core-service=management/management-interface=http-interface&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary/core-service=management/management-interface=http-interface&quot;,
            &quot;attributes&quot; =&gt; [
                &quot;port&quot;,
                &quot;secure-interface&quot;,
                &quot;secure-port&quot;,
                &quot;interface&quot;
            ],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/host=primary/core-service=management/management-interface=native-interface&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary/core-service=management/management-interface=native-interface&quot;,
            &quot;attributes&quot; =&gt; [
                &quot;port&quot;,
                &quot;interface&quot;
            ],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/host=primary/interface=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary/interface=*&quot;,
            &quot;attributes&quot; =&gt; [],
            &quot;entire-resource&quot; =&gt; true,
            &quot;operations&quot; =&gt; [&quot;resolve-internet-address&quot;]
        },
        &quot;/host=primary/server-config=*/interface=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/host=primary/server-config=*/interface=*&quot;,
            &quot;attributes&quot; =&gt; [],
            &quot;entire-resource&quot; =&gt; true,
            &quot;operations&quot; =&gt; []
        },
        &quot;/interface=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/interface=*&quot;,
            &quot;attributes&quot; =&gt; [],
            &quot;entire-resource&quot; =&gt; true,
            &quot;operations&quot; =&gt; []
        },
        &quot;/profile=*/subsystem=messaging/hornetq-server=*/broadcast-group=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/profile=*/subsystem=messaging/hornetq-server=*/broadcast-group=*&quot;,
            &quot;attributes&quot; =&gt; [
                &quot;group-address&quot;,
                &quot;group-port&quot;,
                &quot;local-bind-address&quot;,
                &quot;local-bind-port&quot;
            ],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/profile=*/subsystem=messaging/hornetq-server=*/discovery-group=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/profile=*/subsystem=messaging/hornetq-server=*/discovery-group=*&quot;,
            &quot;attributes&quot; =&gt; [
                &quot;group-address&quot;,
                &quot;group-port&quot;,
                &quot;local-bind-address&quot;
            ],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/profile=*/subsystem=transactions&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/profile=*/subsystem=transactions&quot;,
            &quot;attributes&quot; =&gt; [&quot;process-id-socket-max-ports&quot;],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/server-group=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/server-group=*&quot;,
            &quot;attributes&quot; =&gt; [&quot;socket-binding-port-offset&quot;],
            &quot;entire-resource&quot; =&gt; false,
            &quot;operations&quot; =&gt; []
        },
        &quot;/socket-binding-group=*&quot; =&gt; {
            &quot;address&quot; =&gt; &quot;/socket-binding-group=*&quot;,
            &quot;attributes&quot; =&gt; [],
            &quot;entire-resource&quot; =&gt; true,
            &quot;operations&quot; =&gt; []
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>There will be a separate child for each address to which the
classification applies. The <code>entire-resource</code> attribute will be true if
the classification applies to the entire resource. Otherwise, the
<code>attributes</code> and <code>operations</code> attributes will include the names of
attributes or operations to which the classification applies.</p>
</div>
<div class="sect6">
<h7 id="classifications-with-broad-use"><a class="anchor" href="#classifications-with-broad-use"></a><a class="link" href="#classifications-with-broad-use">Classifications with broad use</a></h7>
<div class="paragraph">
<p>Several of the core sensitivity classifications are commonly used across
the management model and deserve special mention.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">credential</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An attribute whose value is some sort of credential, e.g. a
password or a username. By default sensitive for both reads and writes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">security-domain-ref</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An attribute whose value is the name of a security
domain. By default sensitive for both reads and writes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">security-realm-ref</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An attribute whose value is the name of a security
realm. By default sensitive for both reads and writes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">socket-binding-ref</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An attribute whose value is the name of a socket
binding. By default not sensitive for any action</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">socket-config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A resource, attribute or operation that somehow relates
to configuring a socket. By default sensitive for writes</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect5">
<h6 id="values-with-security-vault-expressions"><a class="anchor" href="#values-with-security-vault-expressions"></a><a class="link" href="#values-with-security-vault-expressions">Values with security vault expressions</a></h6>
<div class="paragraph">
<p>By default any attribute or operation parameter whose value includes a
security vault expression will be treated as sensitive, even if no
sensitivity classification applies or the classification does not treat
the action as sensitive.</p>
</div>
<div class="paragraph">
<p>This setting can be <strong>globally</strong> changed via the CLI. There is a resource
for this configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] cd core-service=management/access=authorization/constraint=vault-expression
[domain@localhost:9990 constraint=vault-expression] ls -l
ATTRIBUTE                 VALUE     TYPE
configured-requires-read  undefined BOOLEAN
configured-requires-write undefined BOOLEAN
default-requires-read     true      BOOLEAN
default-requires-write    true      BOOLEAN</code></pre>
</div>
</div>
<div class="paragraph">
<p>The various <code>default-requires-&#8230;&#8203;</code> attributes indicate whether a user
must be in a role that allows security sensitive actions in order to
perform the action. So, by default both reading and writing attributes
whose values include vault expressions requires a user to be in one of
the roles with sensitive data permissions.</p>
</div>
<div class="paragraph">
<p>The <code>default-requires-&#8230;&#8203;</code> attributes are read-only. The
<code>configured-requires-&#8230;&#8203;</code> attributes however can be modified to override
the default settings with settings appropriate for your organization.
For example, if your organization doesn&#8217;t regard reading vault
expressions to be security sensitive, you can change that setting:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 constraint=vault-expression] :write-attribute(name=configured-requires-read,value=false)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This vault-expression constraint overlaps somewhat with the
<a href="#classifications-with-broad-use">core
"credential" sensitivity classification</a> in that the most typical uses
of a vault expression are in attributes that contain a user name or
password, and those will typically be annotated with the "credential"
sensitivity classification. So, if you change the settings for the
"credential" sensitivity classification you may also need to make a
corresponding change to the vault-expression constraint settings, or
your change will not have full effect.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Be aware though, that vault expressions can be used in any attribute
that supports expressions, not just in credential-type attributes. So it
is important to be familiar with where and how your organization uses
vault expressions before changing these settings.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="configuring-deployer-role-access"><a class="anchor" href="#configuring-deployer-role-access"></a><a class="link" href="#configuring-deployer-role-access">Configuring "Deployer" role access</a></h5>
<div class="paragraph">
<p>The standard <a href="#standard-rbac-roles">Deployer role</a>
has its write permissions limited to resources that are considered to be
"application resources"; i.e. conceptually part of an application and
not part of the general server configuration. By default, only
deployment resources are considered to be application resources.
However, different organizations may have different opinions on what
qualifies as an application resource, so for resource types that
subsystems authors consider <em>potentially</em> to be application resources,
WildFly provides a configuration option to declare them as such. Such
resources will be annotated with an "application classification".</p>
</div>
<div class="paragraph">
<p>For example, the mail subsystem provides such a classification:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] cd /core-service=management/access=authorization/constraint=application-classification/type=mail/classification=mail-session
[domain@localhost:9990 classification=mail-session] ls -l
ATTRIBUTE              VALUE     TYPE
configured-application undefined BOOLEAN
default-application    false     BOOLEAN
 
CHILD      MIN-OCCURS MAX-OCCURS
applies-to n/a        n/a</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use <code>read-resource</code> or <code>read-children-resources</code> to see what resources
have this classification applied:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 classification=mail-session] :read-children-resources(child-type=applies-to)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;/profile=*/subsystem=mail/mail-session=*&quot; =&gt; {
        &quot;address&quot; =&gt; &quot;/profile=*/subsystem=mail/mail-session=*&quot;,
        &quot;attributes&quot; =&gt; [],
        &quot;entire-resource&quot; =&gt; true,
        &quot;operations&quot; =&gt; []
    }}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This indicates that this classification, intuitively enough, only
applies to mail subsystem mail-session resources.</p>
</div>
<div class="paragraph">
<p>To make resources with this classification writeable by users in the
Deployer role, set the <code>configured-application</code> attribute to true.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 classification=mail-session] :write-attribute(name=configured-application,value=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {
        &quot;server-one&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}},
        &quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {&quot;outcome&quot; =&gt; &quot;success&quot;}}
    }}}}
}</code></pre>
</div>
</div>
<div class="sect5">
<h6 id="application-classifications-shipped-with-wildfly"><a class="anchor" href="#application-classifications-shipped-with-wildfly"></a><a class="link" href="#application-classifications-shipped-with-wildfly">Application classifications shipped with WildFly</a></h6>
<div class="paragraph">
<p>The subsystems shipped with the full WildFly distribution include the
following application classifications:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Subsystem</th>
<th class="tableblock halign-left valign-top">Classification</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">datasources</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">data-source</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">datasources</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc-driver</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">datasources</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">xa-data-source</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">logging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">logger</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">logging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">logging-profile</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mail</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">mail-session</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">messaging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jms-queue</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">messaging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jms-topic</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">messaging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">queue</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">messaging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">security-setting</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">naming</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">binding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">resource-adapters</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">resource-adapter</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">security</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">security-domain</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In each case the classification applies to the resources you would
expect, given its name.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="rbac-effect-on-administrator-user-experience"><a class="anchor" href="#rbac-effect-on-administrator-user-experience"></a><a class="link" href="#rbac-effect-on-administrator-user-experience">5.2.7. RBAC effect on administrator user experience</a></h4>
<div class="paragraph">
<p>The RBAC scheme will result in reduced permissions for administrators
who do not map to the SuperUser role, so this will of course have some
impact on their experience when using administrative tools like the
admin console and the CLI.</p>
</div>
<div class="sect4">
<h5 id="admin-console"><a class="anchor" href="#admin-console"></a><a class="link" href="#admin-console">Admin console</a></h5>
<div class="paragraph">
<p>The admin console takes great pains to provide a good user experience
even when the user has reduced permissions. Resources the user is not
permitted to see will simply not be shown, or if appropriate will be
replaced in the UI with an indication that the user is not authorized.
Interaction units like "Add" and "Remove" buttons and "Edit" links will
be suppressed if the user has no write permissions.</p>
</div>
</div>
<div class="sect4">
<h5 id="cli"><a class="anchor" href="#cli"></a><a class="link" href="#cli">CLI</a></h5>
<div class="paragraph">
<p>The CLI is a much more unconstrained tool than the admin console is,
allowing users to try to execute whatever operations they wish, so it&#8217;s
more likely that users who attempt to do things for which they lack
necessary permissions will receive failure messages. For example, a user
in the Monitor role cannot read passwords:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=password)
{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;failure-description&quot; =&gt; &quot;WFLYCTL0313: Unauthorized to execute operation 'read-attribute' for resource '[
    (\&quot;profile\&quot; =&gt; \&quot;default\&quot;),
    (\&quot;subsystem\&quot; =&gt; \&quot;datasources\&quot;),
    (\&quot;data-source\&quot; =&gt; \&quot;ExampleDS\&quot;)
]' -- \&quot;WFLYCTL0332: Permission denied\&quot;&quot;,
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the user isn&#8217;t even allowed to
<a href="#addressing-a-resource">address the resource</a> then the
response would be as if the resource doesn&#8217;t exist, even though it
actually does:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /profile=default/subsystem=elytron/security-domain=ManagementDomain:read-resource
{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;WFLYCTL0216: Management resource '[
    (\&quot;profile\&quot; =&gt; \&quot;default\&quot;),
    (\&quot;subsystem\&quot; =&gt; \&quot;elytron\&quot;),
    (\&quot;security-domain\&quot; =&gt; \&quot;ManagementDomain\&quot;)
]' not found&quot;,
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This prevents unauthorized users fishing for sensitive data in resource
addresses by checking for "Permission denied" type failures.</p>
</div>
<div class="paragraph">
<p>Users who use the <code>read-resource</code> operation may ask for data, some of
which they are allowed to see and some of which they are not. If this
happens, the request will not fail, but inaccessible data will be elided
and a response header will be included advising on what was not
included. Here we show the effect of a Monitor trying to recursively
read the elytron subsystem configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /profile=default/subsystem=elytron:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;security-properties&quot; =&gt; undefined,
        &quot;security-domain&quot; =&gt; undefined,
        &quot;vault&quot; =&gt; undefined
    },
    &quot;response-headers&quot; =&gt; {&quot;access-control&quot; =&gt; [{
        &quot;absolute-address&quot; =&gt; [
            (&quot;profile&quot; =&gt; &quot;default&quot;),
            (&quot;subsystem&quot; =&gt; &quot;elytron&quot;)
        ],
        &quot;relative-address&quot; =&gt; [],
        &quot;filtered-attributes&quot; =&gt; [&quot;security-properties&quot;],
        &quot;filtered-children-types&quot; =&gt; [&quot;security-domain&quot;]
    }]}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>response-headers</code> section includes access control data in a list
with one element per relevant resource. (In this case there&#8217;s just one.)
The absolute and relative address of the resource is shown, along with
the fact that the value of the <code>deep-copy-subject-mode</code> attribute has
been filtered (i.e. undefined is shown as the value, which may not be
the real value) as well as the fact that child resources of type
<code>security-domain</code> have been filtered.</p>
</div>
</div>
<div class="sect4">
<h5 id="description-of-access-control-constraints-in-the-management-model-metadata"><a class="anchor" href="#description-of-access-control-constraints-in-the-management-model-metadata"></a><a class="link" href="#description-of-access-control-constraints-in-the-management-model-metadata">Description of access control constraints in the management model</a></h5>
<div class="paragraph">
<p>metadata</p>
</div>
<div class="paragraph">
<p>The management model descriptive metadata returned from operations like
<code>read-resource-description</code> and <code>read-operation-description</code> can be
configured to include information describing the access control
constraints relevant to the resource, This is done by using the
<code>access-control</code> parameter. The output will be tailored to the caller&#8217;s
permissions. For example, a user who maps to the Monitor role could ask
for information about a resource in the mail subsystem:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] cd /profile=default/subsystem=mail/mail-session=default/server=smtp
[domain@localhost:9990 server=smtp] :read-resource-description(access-control=trim-descriptions)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;description&quot; =&gt; undefined,
        &quot;access-constraints&quot; =&gt; {&quot;application&quot; =&gt; {&quot;mail-session&quot; =&gt; {&quot;type&quot; =&gt; &quot;mail&quot;}}},
        &quot;attributes&quot; =&gt; undefined,
        &quot;operations&quot; =&gt; undefined,
        &quot;children&quot; =&gt; {},
        &quot;access-control&quot; =&gt; {
            &quot;default&quot; =&gt; {
                &quot;read&quot; =&gt; true,
                &quot;write&quot; =&gt; false,
                &quot;attributes&quot; =&gt; {
                    &quot;outbound-socket-binding-ref&quot; =&gt; {
                        &quot;read&quot; =&gt; true,
                        &quot;write&quot; =&gt; false
                    },
                    &quot;username&quot; =&gt; {
                        &quot;read&quot; =&gt; false,
                        &quot;write&quot; =&gt; false
                    },
                    &quot;tls&quot; =&gt; {
                        &quot;read&quot; =&gt; true,
                        &quot;write&quot; =&gt; false
                    },
                    &quot;ssl&quot; =&gt; {
                        &quot;read&quot; =&gt; true,
                        &quot;write&quot; =&gt; false
                    },
                    &quot;password&quot; =&gt; {
                        &quot;read&quot; =&gt; false,
                        &quot;write&quot; =&gt; false
                    }
                }
            },
            &quot;exceptions&quot; =&gt; {}
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Because <code>trim-descriptions</code> was used as the value for the
<code>access-control</code> parameter, the typical "description", "attributes",
"operations" and "children" data is largely suppressed. (For more on
this, <a href="#access-control-param">see below</a>.) The
<code>access-constraints</code> field indicates that this resource is annotated
with an application constraint. The <code>access-control</code> field includes information about the
permissions the current caller has for this resource. The <code>default</code>
section shows the default settings for resources of this type. The
<code>read</code> and <code>write</code> fields directly under <code>default</code> show that the caller
can, in general, read this resource but cannot write it. The
<code>attributes</code> section shows the individual attribute settings. Note that
Monitor cannot read the <code>username</code> and <code>password</code> attributes.</p>
</div>
<div class="paragraph">
<p>There are three valid values for the <code>access-control</code> parameter to
<code>read-resource-description</code> and <code>read-operation-description</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>none</strong> – do not include access control information in the response.
This is the default behavior if no parameter is included.</p>
</li>
<li>
<p><strong>trim-descriptions</strong> – remove the normal description details, as shown
in the example above</p>
</li>
<li>
<p><strong>combined-descriptions</strong> – include both the normal output and the
access control data</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="learning-about-your-own-role-mappings"><a class="anchor" href="#learning-about-your-own-role-mappings"></a><a class="link" href="#learning-about-your-own-role-mappings">5.2.8. Learning about your own role mappings</a></h4>
<div class="paragraph">
<p>Users can learn in which roles they are operating. In the admin console,
click on your name in the top right corner; the roles you are in will be
shown.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="callersroles.png" alt="images/callersroles.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>CLI users should use the <code>whoami</code> operation with the <code>verbose</code> attribute
set:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] :whoami(verbose=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;identity&quot; =&gt; {
            &quot;username&quot; =&gt; &quot;aadams&quot;,
            &quot;realm&quot; =&gt; &quot;ManagementRealm&quot;
        },
        &quot;mapped-roles&quot; =&gt; [
            &quot;Maintainer&quot;
        ]
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="run-as-capability-for-superusers"><a class="anchor" href="#run-as-capability-for-superusers"></a><a class="link" href="#run-as-capability-for-superusers">5.2.9. "Run-as" capability for SuperUsers</a></h4>
<div class="paragraph">
<p>If a user maps to the SuperUser role, WildFly also supports letting that
user request that they instead map to one or more other roles. This can
be useful when doing demos, or when the SuperUser is changing the RBAC
configuration and wants to see what effect the changes have from the
perspective of a user in another role. This capability is only available
to the SuperUser role, so it can only be used to narrow a user&#8217;s
permissions, not to potentially increase them.</p>
</div>
<div class="sect4">
<h5 id="cli-run-as"><a class="anchor" href="#cli-run-as"></a><a class="link" href="#cli-run-as">CLI run-as</a></h5>
<div class="paragraph">
<p>With the CLI, run-as capability is on a per-request basis. It is done by
using the "roles" operation header, the value of which can be the name
of a single role or a bracket-enclosed, comma-delimited list of role
names.</p>
</div>
<div class="paragraph">
<p>Example with a low level operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :whoami(verbose=true){roles=[Operator,Auditor]}
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;identity&quot; =&gt; {
            &quot;username&quot; =&gt; &quot;$local&quot;,
            &quot;realm&quot; =&gt; &quot;ManagementRealm&quot;
        },
        &quot;mapped-roles&quot; =&gt; [
            &quot;Auditor&quot;,
            &quot;Operator&quot;
        ]
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Example with a CLI command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] deploy /tmp/helloworld.war --headers={roles=Monitor}
{&quot;WFLYCTL0062: Composite operation failed and was rolled back. Steps that failed:&quot; =&gt; {&quot;Operation step-1&quot; =&gt; &quot;WFLYCTL0313: Unauthorized to execute operation 'add' for resource '[(\&quot;deployment\&quot; =&gt; \&quot;helloworld.war\&quot;)]' -- \&quot;WFLYCTL0332: Permission denied\&quot;&quot;}}
[standalone@localhost:9990 /] deploy /tmp/helloworld.war --headers={roles=Maintainer}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here we show the effect of switching to a role that isn&#8217;t granted the
necessary permission.</p>
</div>
</div>
<div class="sect4">
<h5 id="admin-console-run-as"><a class="anchor" href="#admin-console-run-as"></a><a class="link" href="#admin-console-run-as">Admin console run-as</a></h5>
<div class="paragraph">
<p>Admin console users can change the role in which they operate by
clicking on their name in the top right corner and clicking on the "Run
as&#8230;&#8203;" link.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="callersroles.png" alt="images/callersroles.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>Then select the role in which you wish to operate:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="runasrole.png" alt="images/runasrole.png" width="450"></span></p>
</div>
<div class="paragraph">
<p>The console will need to be restarted in order for the change to take
effect.</p>
</div>
</div>
<div class="sect4">
<h5 id="using-run-as-roles-with-the-simple-access-control-provider"><a class="anchor" href="#using-run-as-roles-with-the-simple-access-control-provider"></a><a class="link" href="#using-run-as-roles-with-the-simple-access-control-provider">Using run-as roles with the "simple" access control provider</a></h5>
<div class="paragraph">
<p>This "run-as" capability is available even if the "simple" access
control provider is used. When the "simple" provider is used, any
authenticated administrator is treated the same as if they would map to
SuperUser when the "rbac" provider is used.<br>
However, the "simple" provider actually understands all of the "rbac"
provider configuration settings described above, but only makes use of
them if the "run-as" capability is used for a request. Otherwise, the
SuperUser role has all permissions, so detailed configuration is
irrelevant.</p>
</div>
<div class="paragraph">
<p>Using the run-as capability with the "simple" provider may be useful if
an administrator is setting up an rbac provider configuration before
switching the provider to rbac to make that configuration take effect.
The administrator can then run-as different roles to see the effect of
the planned settings.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="application-deployment"><a class="anchor" href="#application-deployment"></a><a class="link" href="#application-deployment">6. Application deployment</a></h2>
<div class="sectionbody">
<!-- toc disabled -->
<div class="sect2">
<h3 id="managed-domain-3"><a class="anchor" href="#managed-domain-3"></a><a class="link" href="#managed-domain-3">6.1. Managed Domain</a></h3>
<div class="paragraph">
<p>In a managed domain, deployments are associated with a <code>server-group</code>
(see <a href="#Core_management_concepts">Core management concepts</a>).
Any server within the server group will then be provided with that
deployment.</p>
</div>
<div class="paragraph">
<p>The domain and host controller components manage the distribution of
binaries across network boundaries.</p>
</div>
<div class="sect3">
<h4 id="deployment-commands"><a class="anchor" href="#deployment-commands"></a><a class="link" href="#deployment-commands">6.1.1. Deployment Commands</a></h4>
<div class="paragraph">
<p>Distributing deployment binaries involves two steps: uploading the
deployment to the repository the domain controller will use to
distribute its contents, and then assigning the deployment to one or
more server groups.</p>
</div>
<div class="paragraph">
<p>You can do this in one sweep with the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] deploy ~/Desktop/test-application.war
Either --all-server-groups or --server-groups must be specified.

[domain@localhost:9990 /] deploy ~/Desktop/test-application.war --all-server-groups
'test-application.war' deployed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>The deployment will be available to the domain controller, assigned to a
server group, and deployed on all running servers in that group:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] :read-children-names(child-type=deployment)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [
       &quot;mysql-connector-java-5.1.15.jar&quot;,
       &quot;test-application.war&quot;
   ]
}

[domain@localhost:9990 /] /server-group=main-server-group/deployment=test-application.war:read-resource(include-runtime)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; {
       &quot;enabled&quot; =&gt; true,
       &quot;name&quot; =&gt; &quot;test-application.war&quot;,
       &quot;managed&quot; =&gt; true,
       &quot;runtime-name&quot; =&gt; &quot;test-application.war&quot;
   }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you only want the deployment deployed on servers in some server
groups, but not all, use the <code>--server-groups</code> parameter instead of
<code>-all-server-groups</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] deploy ~/Desktop/test-application.war --server-groups=main-server-group,another-group
'test-application.war' deployed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you have a new version of the deployment that you want to deploy
replacing an existing one, use the <code>--force</code> parameter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] deploy ~/Desktop/test-application.war --all-server-groups --force
'test-application.war' deployed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can remove binaries from server groups with the <code>undeploy</code> command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] undeploy test-application.war --all-relevant-server-groups
Successfully undeployed test-application.war.

[domain@localhost:9990 /] /server-group=main-server-group:read-children-names(child-type=deployment)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; []
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you only want to undeploy from some server groups but not others, use
the <code>-</code> <code>server-groups</code> parameter instead of
<code>-all-relevant-server-groups</code>.</p>
</div>
<div class="paragraph">
<p>The CLI <code>deploy</code> command supports a number of other parameters that can
control behavior. Use the <code>--help</code> parameter to learn more:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] deploy --help
[...]</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Managing deployments through the web interface provides an alternate,
sometimes simpler approach.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="exploded-managed-deployments"><a class="anchor" href="#exploded-managed-deployments"></a><a class="link" href="#exploded-managed-deployments">6.1.2. Exploded managed deployments</a></h4>
<div class="paragraph">
<p>Managed and unmanaged deployments can be 'exploded', i.e. on the
filesystem in the form of a directory structure whose structure
corresponds to an unzipped version of the archive. An exploded
deployment can be convenient to administer if your administrative
processes involve inserting or replacing files from a base version in
order to create a version tailored for a particular use (for example,
copy in a base deployment and then copy in a jboss-web.xml file to
tailor a deployment for use in WildFly.) Exploded deployments are also
nice in some development scenarios, as you can replace static content
(e.g. .html, .css) files in the deployment and have the new content
visible immediately without requiring a redeploy.</p>
</div>
<div class="paragraph">
<p>Since unmanaged deployment content is directly in your charge, the
following operations only make sense for a managed deployment.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] /deployment=exploded.war:add(content=[{empty=true}])</pre>
</div>
</div>
<div class="paragraph">
<p>This will create an empty exploded deployment to which you&#8217;ll be able to
add content. The <strong>empty</strong> content parameter is required to check that you
really intend to create an empty deployment and not just forget to
define the content.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] /deployment=kitchensink.ear:explode()</pre>
</div>
</div>
<div class="paragraph">
<p>This will 'explode' an existing archive deployment to its exploded
format. This operation is not recursive so you need to explode the
sub-deployment if you want to be able to manipulate the sub-deployment
content. You can do this by specifying the sub-deployment archive <strong>path</strong>
as a parameter to the explode operation.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] /deployment=kitchensink.ear:explode(path=wildfly-kitchensink-ear-web.war)</pre>
</div>
</div>
<div class="paragraph">
<p>Now you can add or remove content to your exploded deployment. Note that
per-default this will overwrite existing contents, you can specify the
overwrite parameter to make the operation fail if the content already
exists.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] /deployment=exploded.war:add-content(content=[{target-path=WEB-INF/classes/org/jboss/as/test/deployment/trivial/ServiceActivatorDeployment.class, input-stream-index=/home/demo/org/jboss/as/test/deployment/trivial/ServiceActivatorDeployment.class}, {target-path=META-INF/MANIFEST.MF, input-stream-index=/home/demo/META-INF/MANIFEST.MF}, {target-path=META-INF/services/org.jboss.msc.service.ServiceActivator, input-stream-index=/home/demo/META-INF/services/org.jboss.msc.service.ServiceActivator}])</pre>
</div>
</div>
<div class="paragraph">
<p>Each content specifies a source content and the target path to which it
will be copied relative to the deployment root. With WildFly 11 you can
use <strong>input-stream-index</strong> (which was a convenient way to pass a stream of
content) from the CLI by pointing it to a local file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] /deployment=exploded.war:remove-content(paths=[WEB-INF/classes/org/jboss/as/test/deployment/trivial/ServiceActivatorDeployment.class, META-INF/MANIFEST.MF, META-INF/services/org.jboss.msc.service.ServiceActivator])</pre>
</div>
</div>
<div class="paragraph">
<p>Now you can list the content of an exploded deployment, or just some
part of it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /deployment=kitchensink.ear:browse-content(archive=false, path=wildfly-kitchensink-ear-web.war)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        {
            &quot;path&quot; =&gt; &quot;META-INF/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/MANIFEST.MF&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 128L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/templates/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/controller/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/rest/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/util/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;resources/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;resources/css/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/templates/default.xhtml&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 2113L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/faces-config.xml&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 1365L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/controller/MemberController.class&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 2750L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/rest/MemberResourceRESTService.class&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 6363L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/rest/JaxRsActivator.class&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 464L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/classes/org/jboss/as/quickstarts/kitchensink_ear/util/WebResources.class&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 667L
        },
        {
            &quot;path&quot; =&gt; &quot;WEB-INF/beans.xml&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 1262L
        },
        {
            &quot;path&quot; =&gt; &quot;index.xhtml&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 3603L
        },
        {
            &quot;path&quot; =&gt; &quot;index.html&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 949L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/css/screen.css&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 4025L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/headerbkg.png&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 1147L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/asidebkg.png&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 1374L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/banner.png&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 41473L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/bkg-blkheader.png&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 116L
        },
        {
            &quot;path&quot; =&gt; &quot;resources/gfx/rhjb_eap_logo.png&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 2637L
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/maven/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/maven/org.wildfly.quickstarts/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/maven/org.wildfly.quickstarts/wildfly-kitchensink-ear-web/&quot;,
            &quot;directory&quot; =&gt; true
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/maven/org.wildfly.quickstarts/wildfly-kitchensink-ear-web/pom.xml&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 4128L
        },
        {
            &quot;path&quot; =&gt; &quot;META-INF/maven/org.wildfly.quickstarts/wildfly-kitchensink-ear-web/pom.properties&quot;,
            &quot;directory&quot; =&gt; false,
            &quot;file-size&quot; =&gt; 146L
        }
    ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You also have a <strong>read-content</strong> operation but since it returns a binary
stream, this is not displayable from the CLI.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /deployment=kitchensink.ear:read-content(path=META-INF/MANIFEST.MF)
{
  &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;uuid&quot; =&gt; &quot;b373d587-72ee-4b1e-a02a-71fbb0c85d32&quot;},
    &quot;response-headers&quot; =&gt; {&quot;attached-streams&quot; =&gt; [{
        &quot;uuid&quot; =&gt; &quot;b373d587-72ee-4b1e-a02a-71fbb0c85d32&quot;,
        &quot;mime-type&quot; =&gt; &quot;text/plain&quot;
    }]}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The management CLI however provides high level commands to display or
save binary stream attachments:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] attachment display --operation=/deployment=kitchensink.ear:read-content(path=META-INF/MANIFEST.MF)
ATTACHMENT d052340a-abb7-4a66-aa24-4eeeb6b256be:
Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Built-By: mjurc
Created-By: Apache Maven 3.3.9
Build-Jdk: 1.8.0_91</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre>[domain@localhost:9990 /] attachment save --operation=/deployment=kitchensink.ear:read-content(path=META-INF/MANIFEST.MF) --file=example
File saved to /home/mjurc/wildfly/build/target/wildfly-11.0.0.Alpha1-SNAPSHOT/example</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="xml-configuration-file"><a class="anchor" href="#xml-configuration-file"></a><a class="link" href="#xml-configuration-file">6.1.3. XML Configuration File</a></h4>
<div class="paragraph">
<p>When you deploy content, the domain controller adds two types of entries
to the <code>domain.xml</code> configuration file, one showing global information
about the deployment, and another for each relevant server group showing
how it is used by that server group:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">[...]
<span class="tag">&lt;deployments&gt;</span>
   <span class="tag">&lt;deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">runtime-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;content</span> <span class="attribute-name">sha1</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">dda9881fa7811b22f1424b4c5acccb13c71202bd</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/deployment&gt;</span>
<span class="tag">&lt;/deployments&gt;</span>
[...]
<span class="tag">&lt;server-groups&gt;</span>
   <span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       [...]
       <span class="tag">&lt;deployments&gt;</span>
           <span class="tag">&lt;deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">runtime-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/deployments&gt;</span>
   <span class="tag">&lt;/server-group&gt;</span>
<span class="tag">&lt;/server-groups&gt;</span>
[...]</code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/domain.xml)~</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="standalone-server-3"><a class="anchor" href="#standalone-server-3"></a><a class="link" href="#standalone-server-3">6.2. Standalone Server</a></h3>
<div class="paragraph">
<p>Deployments on a standalone server work in a similar way to those on
managed domains. The main difference is that there are no server group
associations.</p>
</div>
<div class="sect3">
<h4 id="deployment-commands-1"><a class="anchor" href="#deployment-commands-1"></a><a class="link" href="#deployment-commands-1">6.2.1. Deployment Commands</a></h4>
<div class="paragraph">
<p>The same CLI commands used for managed domains work for standalone
servers when deploying and removing an application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] deploy ~/Desktop/test-application.war
'test-application.war' deployed successfully.

[standalone@localhost:9990 /] undeploy test-application.war
Successfully undeployed test-application.war.</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="deploying-using-the-deployment-scanner"><a class="anchor" href="#deploying-using-the-deployment-scanner"></a><a class="link" href="#deploying-using-the-deployment-scanner">6.2.2. Deploying Using the Deployment Scanner</a></h4>
<div class="paragraph">
<p>Deployment content (for example, war, ear, jar, and sar files) can be
placed in the standalone/deployments directory of the WildFly
distribution, in order to be automatically deployed into the server
runtime. For this to work the <code>deployment-scanner</code> subsystem must be
present. The scanner periodically checks the contents of the deployments
directory and reacts to changes by updating the server.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Users are encouraged to use the WildFly management APIs to upload and
deploy deployment content instead of relying on the deployment scanner
that periodically scans the directory, particularly if running
production systems.
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="deployment-scanner-modes"><a class="anchor" href="#deployment-scanner-modes"></a><a class="link" href="#deployment-scanner-modes">Deployment Scanner Modes</a></h5>
<div class="paragraph">
<p>The WildFly filesystem deployment scanner operates in one of two
different modes, depending on whether it will directly monitor the
deployment content in order to decide to deploy or redeploy it.</p>
</div>
<div class="paragraph">
<p>Auto-deploy mode:</p>
</div>
<div class="paragraph">
<p>The scanner will directly monitor the deployment content, automatically
deploying new content and redeploying content whose timestamp has
changed. This is similiar to the behavior of previous AS releases,
although there are differences:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A change in any file in an exploded deployment triggers redeploy.
Because EE 6+ applications do not require deployment descriptors,<br>
there is no attempt to monitor deployment descriptors and only redeploy
when a deployment descriptor changes.</p>
</li>
<li>
<p>The scanner will place marker files in this directory as an indication
of the status of its attempts to deploy or undeploy content. These are
detailed below.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Manual deploy mode:</p>
</div>
<div class="paragraph">
<p>The scanner will not attempt to directly monitor the deployment content
and decide if or when the end user wishes the content to be deployed.
Instead, the scanner relies on a system of marker files, with the user&#8217;s
addition or removal of a marker file serving as a sort of command
telling the scanner to deploy, undeploy or redeploy content.</p>
</div>
<div class="paragraph">
<p>Auto-deploy mode and manual deploy mode can be independently configured
for zipped deployment content and exploded deployment content. This is
done via the "auto-deploy" attribute on the deployment-scanner element
in the standalone.xml configuration file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;deployment-scanner</span> <span class="attribute-name">scan-interval</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.base.dir</span><span class="delimiter">&quot;</span></span>
   <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">deployments</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-deploy-zipped</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-deploy-exploded</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>By default, auto-deploy of zipped content is enabled, and auto-deploy of
exploded content is disabled. Manual deploy mode is strongly recommended
for exploded content, as exploded content is inherently vulnerable to
the scanner trying to auto-deploy partially copied content.</p>
</div>
</div>
<div class="sect4">
<h5 id="marker-files"><a class="anchor" href="#marker-files"></a><a class="link" href="#marker-files">Marker Files</a></h5>
<div class="paragraph">
<p>The marker files always have the same name as the deployment content to
which they relate, but with an additional file suffix appended. For
example, the marker file to indicate the example.war file should be
deployed is named example.war.dodeploy. Different marker file suffixes
have different meanings.</p>
</div>
<div class="paragraph">
<p>The relevant marker file types are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">File</th>
<th class="tableblock halign-left valign-top">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.dodeploy</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the user to indicate that the given content
should be deployed into the runtime (or redeployed if already deployed in
the runtime.)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.skipdeploy</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Disables auto-deploy of the content for as long as the
file is present. Most useful for allowing updates to exploded content
without having the scanner initiate redeploy in the middle of the update.
Can be used with zipped content as well, although the scanner will detect
in-progress changes to zipped content and wait until changes are
complete.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.isdeploying</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate that
it has noticed a .dodeploy file or new or updated auto-deploymode content
and is in the process of deploying the content.This marker file will be
deleted when the deployment process completes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.deployed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate that
the given content has been deployed into the runtime. If an end user
deletes this file, the content will be undeployed.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.failed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate that
the given content failed to deploy into the runtime. The contentof the
file will include some information about the cause ofthe failure. Note
that with auto-deploy mode, removing this file will make the deployment
eligible for deployment again.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.isundeploying</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate
that it has noticed a .deployed file has been deleted and the content is
being undeployed. This marker file will be deleted when the undeployment
process completes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.undeployed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate that
the given content has been undeployed from the runtime. If an end user
deletes this file, it has no impact.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">.pending</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Placed by the deployment scanner service to indicate that
it has noticed the need to deploy content but has not yet instructed the
server to deploy it. This file is created if the scanner detects that
some auto-deploy content is still in the process of being copied or if
there is some problem that prevents auto-deployment. The scanner will not
instruct the server to deploy or undeploy any content (not just
the directly affected content) as long as this condition holds.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="basic-workflows"><a class="anchor" href="#basic-workflows"></a><a class="link" href="#basic-workflows">Basic workflows:</a></h5>
<div class="paragraph">
<p>All examples assume variable $JBOSS_HOME points to the root of the
WildFly distribution.</p>
</div>
<div class="olist upperalpha">
<ol class="upperalpha" type="A">
<li>
<p>Add new zipped content and deploy it:</p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>cp target/example.war/ $JBOSS_HOME/standalone/deployments</p>
</li>
<li>
<p>(Manual mode only) touch
$JBOSS_HOME/standalone/deployments/example.war.dodeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Add new unzipped content and deploy it:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>cp -r target/example.war/ $JBOSS_HOME/standalone/deployments</p>
</li>
<li>
<p>(Manual mode only) touch
$JBOSS_HOME/standalone/deployments/example.war.dodeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Undeploy currently deployed content:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>rm $JBOSS_HOME/standalone/deployments/example.war.deployed</p>
</li>
</ol>
</div>
</li>
<li>
<p>Auto-deploy mode only: Undeploy currently deployed content:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>rm $JBOSS_HOME/standalone/deployments/example.war</p>
</li>
</ol>
</div>
</li>
<li>
<p>Replace currently deployed zipped content with a new version and deploy it:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>cp target/example.war/ $JBOSS_HOME/standalone/deployments</p>
</li>
<li>
<p>(Manual mode only) touch
$JBOSS_HOME/standalone/deployments/example.war.dodeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Manual mode only: Replace currently deployed unzipped content with a
new version and deploy it:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>rm $JBOSS_HOME/standalone/deployments/example.war.deployed</p>
</li>
<li>
<p>wait for $JBOSS_HOME/standalone/deployments/example.war.undeployed
file to appear</p>
</li>
<li>
<p>cp -r target/example.war/ $JBOSS_HOME/standalone/deployments</p>
</li>
<li>
<p>touch $JBOSS_HOME/standalone/deployments/example.war.dodeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Auto-deploy mode only: Replace currently deployed unzipped content
with a new version and deploy it:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>touch $JBOSS_HOME/standalone/deployments/example.war.skipdeploy</p>
</li>
<li>
<p>cp -r target/example.war/ $JBOSS_HOME/standalone/deployments</p>
</li>
<li>
<p>rm $JBOSS_HOME/standalone/deployments/example.war.skipdeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Manual mode only: Live replace portions of currently deployed
unzipped content without redeploying:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>cp -r target/example.war/foo.html
$JBOSS_HOME/standalone/deployments/example.war</p>
</li>
</ol>
</div>
</li>
<li>
<p>Auto-deploy mode only: Live replace portions of currently deployed
unzipped content without redeploying:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>touch $JBOSS_HOME/standalone/deployments/example.war.skipdeploy</p>
</li>
<li>
<p>cp -r target/example.war/foo.html
$JBOSS_HOME/standalone/deployments/example.war</p>
</li>
</ol>
</div>
</li>
<li>
<p>Manual or auto-deploy mode: Redeploy currently deployed content
(i.e. bounce it with no content change):</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>touch $JBOSS_HOME/standalone/deployments/example.war.dodeploy</p>
</li>
</ol>
</div>
</li>
<li>
<p>Auto-deploy mode only: Redeploy currently deployed content (i.e.
bounce it with no content change):</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>touch $JBOSS_HOME/standalone/deployments/example.war</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The above examples use Unix shell commands. Windows equivalents are:
cp src dest -&#8594; xcopy /y src dest<br>
cp -r src dest -&#8594; xcopy /e /s /y src dest<br>
rm afile -&#8594; del afile<br>
touch afile -&#8594; echo&gt;&gt; afile
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Note that the behavior of 'touch' and 'echo' are different but the
differences are not relevant to the usages in the examples above.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="managed-and-unmanaged-deployments"><a class="anchor" href="#managed-and-unmanaged-deployments"></a><a class="link" href="#managed-and-unmanaged-deployments">6.3. Managed and Unmanaged Deployments</a></h3>
<div class="paragraph">
<p>WildFly supports two mechanisms for dealing with deployment content –
managed and unmanaged deployments.</p>
</div>
<div class="paragraph">
<p>With a managed deployment the server takes the deployment content and
copies it into an internal content repository and thereafter uses that
copy of the content, not the original user-provided content. The server
is thereafter responsible for the content it uses.</p>
</div>
<div class="paragraph">
<p>With an unmanaged deployment the user provides the local filesystem path
of deployment content, and the server directly uses that content.
However, the user is responsible for ensuring that content, e.g. for
making sure that no changes are made to it that will negatively impact
the functioning of the deployed application.</p>
</div>
<div class="paragraph">
<p>To help you differentiate managed from unmanaged deployments the
deployment model has a runtime boolean attribute 'managed'.</p>
</div>
<div class="paragraph">
<p>Managed deployments have a number of benefits over unmanaged:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>They can be manipulated by remote management clients, not requiring
access to the server filesystem.</p>
</li>
<li>
<p>In a managed domain, WildFly/EAP will take responsibility for
replicating a copy of the deployment to all hosts/servers in the domain
where it is needed. With an unmanaged deployment, it is the user&#8217;s
responsibility to have the deployment available on the local filesystem
on all relevant hosts, at a consistent path.</p>
</li>
<li>
<p>The deployment content actually used is stored on the filesystem in
the internal content repository, which should help shelter it from
unintended changes.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>All of the previous examples above illustrate using managed deployments,
except for any discussion of deployment scanner handling of exploded
deployments. In WildFly 10 and earlier exploded deployments are always
unmanaged, this is no longer the case since WildFly 11.</p>
</div>
<div class="sect3">
<h4 id="content-repository"><a class="anchor" href="#content-repository"></a><a class="link" href="#content-repository">6.3.1. Content Repository</a></h4>
<div class="paragraph">
<p>For a managed deployment, the actual file the server uses when creating
runtime services is not the file provided to the CLI <code>deploy</code> command or
to the web console. It is a copy of that file stored in an internal
content repository. The repository is located in the
<code>domain/data/content</code> directory for a managed domain, or in
<code>standalone/data/content</code> for a standalone server. Actual binaries are
stored in a subdirectory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>ls domain/data/content/
  |---/47
  |-----95cc29338b5049e238941231b36b3946952991
  |---/dd
  |-----a9881fa7811b22f1424b4c5acccb13c71202bd</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The location of the content repository and its internal structure is
subject to change at any time and should not be relied upon by end
users.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The description of a managed deployment in the domain or standalone
configuration file includes an attribute recording the SHA1 hash of the
deployment content:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;deployments&gt;</span>
   <span class="tag">&lt;deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">runtime-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-application.war</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;content</span> <span class="attribute-name">sha1</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">dda9881fa7811b22f1424b4c5acccb13c71202bd</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/deployment&gt;</span>
<span class="tag">&lt;/deployments&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The WildFly process calculates and records that hash when the user
invokes a management operation (e.g. CLI <code>deploy</code> command or using the
console) providing deployment content. The user is not expected to
calculate the hash.</p>
</div>
<div class="paragraph">
<p>The sha1 attribute in the content element tells the WildFly process
where to find the deployment content in its internal content repository.</p>
</div>
<div class="paragraph">
<p>In a domain each host will have a copy of the content needed by its
servers in its own local content repository. The WildFly domain
controller and secondary Host Controller processes take responsibility for
ensuring each host has the needed content.</p>
</div>
</div>
<div class="sect3">
<h4 id="unmanaged-deployments"><a class="anchor" href="#unmanaged-deployments"></a><a class="link" href="#unmanaged-deployments">6.3.2. Unmanaged Deployments</a></h4>
<div class="paragraph">
<p>An unmanaged deployment is one where the server directly deploys the
content at a path you specify instead of making an internal copy and
then deploying the copy.</p>
</div>
<div class="paragraph">
<p>Initially deploying an unmanaged deployment is much like deploying a
managed one, except you tell WildFly that you do not want the deployment
to be managed:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] deploy ~/Desktop/test-application.war --unmanaged
'test-application.war' deployed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>When you do this, instead of the server making a copy of the content at
<code>/Desktop/test-application.war</code>, calculating the hash of the content,
storing the hash in the configuration file and then installing the copy
into the runtime, instead it will convert
<code>/Desktop/test-application.war</code> to an absolute path, store the path in
the configuration file, and then install the original content in the
runtime.</p>
</div>
<div class="paragraph">
<p>You can also use unmanaged deployments in a domain:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] deploy /home/example/Desktop/test-application.war --server-group=main-server-group --unmanaged
'test-application.war' deployed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p>However, before you run this command you must ensure that a copy of the
content is present on all machines that have servers in the target
server groups, all at the same filesystem path. The domain will not copy
the file for you.</p>
</div>
<div class="paragraph">
<p>Undeploy is no different from a managed undeploy:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] undeploy test-application.war
Successfully undeployed test-application.war.</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing a replacement of the deployment with a new version is a bit
different, the server is using the file you want to replace. You should
undeploy the deployment, replace the content, and then deploy again. Or
you can stop the server, replace the deployment and deploy again.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Deployment_Overlays"><a class="anchor" href="#Deployment_Overlays"></a><a class="link" href="#Deployment_Overlays">6.4. Deployment Overlays</a></h3>
<div class="paragraph">
<p>Deployment overlays are our way of 'overlaying' content into an existing
deployment, without physically modifying the contents of the deployment
archive. Possible use cases include swapping out deployment descriptors,
modifying static web resources to change the branding of an application,
or even replacing jar libraries with different versions.</p>
</div>
<div class="paragraph">
<p>Deployment overlays have a different lifecycle to a deployment. In order
to use a deployment overlay, you first create the overlay, using the CLI
or the management API. You then add files to the overlay, specifying the
deployment paths you want them to overlay. Once you have created the
overlay you then have to link it to a deployment name (which is done
slightly differently depending on if you are in standalone or domain
mode). Once you have created the link any deployment that matches the
specified deployment name will have the overlay applied.</p>
</div>
<div class="paragraph">
<p>When you modify or create an overlay it will not affect existing
deployments, they must be redeployed in order to take effect</p>
</div>
<div class="sect3">
<h4 id="creating-a-deployment-overlay"><a class="anchor" href="#creating-a-deployment-overlay"></a><a class="link" href="#creating-a-deployment-overlay">6.4.1. Creating a deployment overlay</a></h4>
<div class="paragraph">
<p>To create a deployment overlay the CLI provides a high level command to
do all the steps specified above in one go. An example command is given
below for both standalone and domain mode:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>deployment-overlay add --name=myOverlay --content=/WEB-INF/web.xml=/myFiles/myWeb.xml,/WEB-INF/ejb-jar.xml=/myFiles/myEjbJar.xml --deployments=test.war,*-admin.war --redeploy-affected</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>deployment-overlay add --name=myOverlay --content=/WEB-INF/web.xml=/myFiles/myWeb.xml,/WEB-INF/ejb-jar.xml=/myFiles/myEjbJar.xml --deployments=test.war,*-admin.war --server-groups=main-server-group --redeploy-affected</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Subsystem_configuration"><a class="anchor" href="#Subsystem_configuration"></a><a class="link" href="#Subsystem_configuration">7. Subsystem configuration</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Subsystem configuration reference
:author: <a href="mailto:tcerar@redhat.com">tcerar@redhat.com</a>
:icons: font
:source-highlighter: coderay
:toc: macro
:toclevels: 2</p>
</div>
<!-- toc disabled -->
<div class="paragraph">
<p>The following chapters will focus on the high level management use cases
that are available through the CLI and the web interface. For a detailed
description of each subsystem configuration property, please consult the
respective component reference.</p>
</div>
<div class="paragraph">
<p>Schema Location</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The configuration schemas can found in <code>$JBOSS_HOME/docs/schema</code>.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="EE"><a class="anchor" href="#EE"></a><a class="link" href="#EE">7.1. EE Subsystem Configuration</a></h3>
<div class="paragraph">
<p>The EE subsystem provides common functionality in the Jakarta EE platform,
such as the EE Concurrency Utilities (JSR 236) and <code>@Resource</code>
injection. The subsystem is also responsible for managing the lifecycle
of Jakarta EE application&#8217;s deployments, that is, <code>.ear</code> files and configuration of global directories to share common libraries across all deployed applications.</p>
</div>
<div class="paragraph">
<p>The EE subsystem configuration may be used to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>customise the deployment of Jakarta EE applications</p>
</li>
<li>
<p>create EE Concurrency Utilities instances</p>
</li>
<li>
<p>define the default bindings</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The subsystem name is ee and this document covers EE subsystem version
<code>5.0</code>, which XML namespace within WildFly XML configurations is
<code>urn:jboss:domain:ee:5.0</code>. The path for the subsystem&#8217;s XML schema,
within WildFly&#8217;s distribution, is <code>docs/schema/jboss-as-ee_5_0.xsd</code>.</p>
</div>
<div class="paragraph">
<p>Subsystem XML configuration example with all elements and attributes
specified:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:ee:5.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;global-modules&gt;</span>
        <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.logging</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">slot</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.apache.logging.log4j.api</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">annotations</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">meta-inf</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">services</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/global-modules&gt;</span>
    <span class="tag">&lt;global-directories&gt;</span>
        <span class="tag">&lt;directory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">common-libs</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">libs</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.base.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/global-directories&gt;</span>
    <span class="tag">&lt;ear-subdeployments-isolated&gt;</span>true<span class="tag">&lt;/ear-subdeployments-isolated&gt;</span>
    <span class="tag">&lt;spec-descriptor-property-replacement&gt;</span>false<span class="tag">&lt;/spec-descriptor-property-replacement&gt;</span>
    <span class="tag">&lt;jboss-descriptor-property-replacement&gt;</span>false<span class="tag">&lt;/jboss-descriptor-property-replacement&gt;</span>
    <span class="tag">&lt;annotation-property-replacement&gt;</span>false<span class="tag">&lt;/annotation-property-replacement&gt;</span>
    <span class="tag">&lt;concurrent&gt;</span>
        <span class="tag">&lt;context-services&gt;</span>
            <span class="tag">&lt;context-service</span>
                    <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/context/default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">use-transaction-setup-provider</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;/context-services&gt;</span>
        <span class="tag">&lt;managed-thread-factories&gt;</span>
            <span class="tag">&lt;managed-thread-factory</span>
                    <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/factory/default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">priority</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;/managed-thread-factories&gt;</span>
        <span class="tag">&lt;managed-executor-services&gt;</span>
            <span class="tag">&lt;managed-executor-service</span>
                    <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/executor/default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">hung-task-threshold</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60000</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">core-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">max-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">25</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">keepalive-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">queue-length</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1000000</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">reject-policy</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">RETRY_ABORT</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;/managed-executor-services&gt;</span>
        <span class="tag">&lt;managed-scheduled-executor-services&gt;</span>
            <span class="tag">&lt;managed-scheduled-executor-service</span>
                    <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/scheduler/default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">hung-task-threshold</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60000</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">core-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">keepalive-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span>
                    <span class="attribute-name">reject-policy</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">RETRY_ABORT</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;/managed-scheduled-executor-services&gt;</span>
    <span class="tag">&lt;/concurrent&gt;</span>
    <span class="tag">&lt;default-bindings</span>
            <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/context/default</span><span class="delimiter">&quot;</span></span>
            <span class="attribute-name">datasource</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleDS</span><span class="delimiter">&quot;</span></span>
            <span class="attribute-name">jms-connection-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/DefaultJMSConnectionFactory</span><span class="delimiter">&quot;</span></span>
            <span class="attribute-name">managed-executor-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/executor/default</span><span class="delimiter">&quot;</span></span>
            <span class="attribute-name">managed-scheduled-executor-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/scheduler/default</span><span class="delimiter">&quot;</span></span>
            <span class="attribute-name">managed-thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/factory/default</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="EE_Application_Deployment_Configuration"><a class="anchor" href="#EE_Application_Deployment_Configuration"></a><a class="link" href="#EE_Application_Deployment_Configuration">7.1.1. Jakarta EE Application Deployment</a></h4>
<div class="paragraph">
<p>The EE subsystem configuration allows the customisation of the
deployment behaviour for Jakarta EE Applications.</p>
</div>
<div class="sect4">
<h5 id="global-modules"><a class="anchor" href="#global-modules"></a><a class="link" href="#global-modules">Global Modules</a></h5>
<div class="paragraph">
<p>Global modules is a set of JBoss Modules that will be added as
dependencies to the JBoss Modules module of every Jakarta EE deployment. Such
dependencies allows Jakarta EE deployments to see the classes exported by
the global modules.</p>
</div>
<div class="paragraph">
<p>Each global module is defined through the <code>module</code> resource, an example
of its XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;global-modules&gt;</span>
    <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.logging</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">slot</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.apache.logging.log4j.api</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">annotations</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">meta-inf</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">services</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  <span class="tag">&lt;/global-modules&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The only mandatory attribute is the JBoss Modules module <code>name</code>, the <code>slot</code>
attribute defaults to <code>main</code>, and both define the JBoss Modules module ID to
reference.</p>
</div>
<div class="paragraph">
<p>The optional <code>annotations</code> attribute, which defaults to <code>false</code>,
indicates if a pre-computed annotation index should be imported from
META-INF/jandex.idx</p>
</div>
<div class="paragraph">
<p>The optional <code>services</code> attribute indicates if any services exposed in
META-INF/services should be made available to the deployments class
loader, and defaults to <code>false</code>.</p>
</div>
<div class="paragraph">
<p>The optional <code>meta-inf</code> attribute, which defaults to <code>true</code>, indicates
if the Module&#8217;s <code>META-INF</code> path should be available to the deployment&#8217;s
class loader.</p>
</div>
</div>
<div class="sect4">
<h5 id="global-directory"><a class="anchor" href="#global-directory"></a><a class="link" href="#global-directory">Global Directory</a></h5>
<div class="paragraph">
<p>Global modules can be used to share common libraries across all deployed applications, but it could be impractical if the name of a shared library changes very often or if there are many libraries you want to share. Both cases will require changes in the underlying module.xml that represents this global module.</p>
</div>
<div class="paragraph">
<p>The EE subsystem allows the configuration of a global directory, which represents a directory tree scanned automatically to include .jar files and resources as a single additional dependency. This module dependency is added as a system dependency on each deployed application. Basically, with a global directory, you will be relying on WildFly to automate the maintenance and configuration of a JBoss Modules module that represents the jar files and resources of a specific directory.</p>
</div>
<div class="paragraph">
<p>You can configure a global directory using the following operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  [standalone@localhost:9990 /] /subsystem=ee/global-directory=my-common-libs:add(path=lib, relative-to=jboss.home.dir)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following attributes are available on the global-directory resource:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>path: The path of the directory to scan. (Mandatory)</p>
</li>
<li>
<p>relative-to: The name of another previously named path, or of one of the standard paths provided by the system. (Optional)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When a <code>global-directory</code> is created, the server establishes a JBoss Modules module with one <a href="https://jboss-modules.github.io/jboss-modules/manual/#path-resource-loader">Path Resource Loader</a> created using 'path' and 'relative-to' attributes and one <a href="https://jboss-modules.github.io/jboss-modules/manual/#jar-resource-loader">Jar Resource loader</a> for each jar file included in this directory and its subdirectories.</p>
</div>
<div class="paragraph">
<p>The 'Path Resource Loader' will make available any file as a resource to the application. The 'Jar Resource loader' will make available any class inside of the jar file to the applications.</p>
</div>
<div class="paragraph">
<p>For example, suppose you have configured one global directory pointing to the following directory tree:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/my-common-libs/Z/a-lib.jar
/my-common-libs/A/A/z-lib.jar
/my-common-libs/A/a-lib.jar
/my-common-libs/A/b-lib.jar
/my-common-libs/a-lib.jar
/my-common-libs/A/B/a-lib.jar
/my-common-libs/properties-1.properties
/my-common-libs/A/B/properties-2.properties</pre>
</div>
</div>
<div class="paragraph">
<p>The JBoss Modules module generated after scanning this global-directory will be equivalent to the following module.xml:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>&lt;module xmlns="urn:jboss:module:1.9" name="deployment.external.global-directory.my-common-libs"&gt;
    &lt;resources&gt;
        &lt;resource-root path="/my-common-libs"/&gt;
        &lt;resource-root path="/my-common-libs/a-lib.jar"/&gt;
        &lt;resource-root path="/my-common-libs/A/a-lib.jar"/&gt;
        &lt;resource-root path="/my-common-libs/A/b-lib.jar"/&gt;
        &lt;resource-root path="/my-common-libs/A/A/z-lib.jar"/&gt;
        &lt;resource-root path="/my-common-libs/A/B/a-lib.jar"/&gt;
        &lt;resource-root path="/my-common-libs/Z/a-lib.jar"/&gt;
    &lt;/resources&gt;

    &lt;dependencies&gt;
        &lt;module name="javaee.api"/&gt;
    &lt;/dependencies&gt;
&lt;/module&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>The name of the generated module follows the pattern <em>deployment.external.global-directory.{global-directory-name}</em> and as such, it can be excluded selectively using your deployment-structure.xml.</p>
</div>
<div class="paragraph">
<p>All resources will be available from the application class loader. For example, you could access the above property files using the context ClassLoader of your current thread:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Thread.currentThread().getContextClassLoader().getResourceAsStream("properties-1.properties");
Thread.currentThread().getContextClassLoader().getResourceAsStream("A/B/properties-2.properties");</pre>
</div>
</div>
<div class="paragraph">
<p>All classes inside of each jar file will also be available, and the order of how the resource-root are created internally will govern the order of the class loading. The jar resources of the generated module will be created iterating over all jar files found in the directory tree. Each directory is scanned alphabetically starting from the root, and on each level, each subdirectory is also explored alphabetically until visiting all the branch. Files found on each level are also added in alphabetical order.</p>
</div>
<div class="paragraph">
<p>Notice you should know which classes are exposed on each .jar file and avoid conflicts including the same class twice with incompatible binary change. In those cases, classloading errors are likely to occur. Specifically, you should not add classes that interfere with the classes the server already makes available for your application; the goal of a global directory is not to override and replace existing library versions shipped with the server. It is a facility that will allow moving common frameworks you usually add to your application libs to a common place to facilitate maintenance.</p>
</div>
<div class="paragraph">
<p>The module created from the shared directory is loaded as soon as the first application is deployed in the server after creating the global-directory. That means, if the server is started/restarted and there are no applications deployed, then the global directory is neither scanned nor the module loaded. Any change in any of the contents of the global-directory will require a server reload to make them available to the deployed applications.</p>
</div>
<div class="paragraph">
<p>In case of domain mode or distributed environments, it is the user responsibility to make the content of the configured global directory consistent across all the server instances, as well as distribute the jar files that they contain.</p>
</div>
</div>
<div class="sect4">
<h5 id="ear-subdeployments-isolation"><a class="anchor" href="#ear-subdeployments-isolation"></a><a class="link" href="#ear-subdeployments-isolation">EAR Subdeployments Isolation</a></h5>
<div class="paragraph">
<p>A flag indicating whether each of the subdeployments within a <code>.ear</code> can
access classes belonging to another subdeployment within the same
<code>.ear</code>. The default value is <code>false</code>, which allows the subdeployments to
see classes belonging to other subdeployments within the <code>.ear</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;ear-subdeployments-isolated&gt;</span>true<span class="tag">&lt;/ear-subdeployments-isolated&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>myapp.ear
|
|--- web.war
|
|--- ejb1.jar
|
|--- ejb2.jar</pre>
</div>
</div>
<div class="paragraph">
<p>If the <code>ear-subdeployments-isolated</code> is set to false, then the classes
in <code>web.war</code> can access classes belonging to <code>ejb1.jar</code> and <code>ejb2.jar</code>.
Similarly, classes from <code>ejb1.jar</code> can access classes from <code>ejb2.jar</code>
(and vice-versa).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This flag has no effect on the isolated classloader of the <code>.war</code>
file(s), i.e. irrespective of whether this flag is set to <code>true</code> or
<code>false</code>, the <code>.war</code> within a <code>.ear</code> will have a isolated classloader,
and other subdeployments within that <code>.ear</code> will not be able to access
classes from that <code>.war</code>. This is as per spec.
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="property-replacement"><a class="anchor" href="#property-replacement"></a><a class="link" href="#property-replacement">Property Replacement</a></h5>
<div class="paragraph">
<p>The EE subsystem configuration includes flags to configure whether
system property replacement will be done on XML descriptors and Java
Annotations included in Jakarta EE deployments.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
System properties etc are resolved in the security context of the
application server itself, not the deployment that contains the file.
This means that if you are running with a security manager and enable
this property, a deployment can potentially access system properties or
environment entries that the security manager would have otherwise
prevented.
</td>
</tr>
</table>
</div>
<div class="sect5">
<h6 id="spec-descriptor-property-replacement"><a class="anchor" href="#spec-descriptor-property-replacement"></a><a class="link" href="#spec-descriptor-property-replacement">Spec Descriptor Property Replacement</a></h6>
<div class="paragraph">
<p>Flag indicating whether system property replacement will be performed on
standard Jakarta EE XML descriptors. If not configured this defaults to
<code>true</code>, however it is set to <code>false</code> in the standard configuration files
shipped with WildFly.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;spec-descriptor-property-replacement&gt;</span>false<span class="tag">&lt;/spec-descriptor-property-replacement&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>When enabled, properties can be replaced in the following deployment descriptors:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ejb-jar.xml</p>
</li>
<li>
<p>persistence.xml</p>
</li>
<li>
<p>application.xml</p>
</li>
<li>
<p>web.xml</p>
</li>
<li>
<p>permissions.xml</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6 id="jboss-descriptor-property-replacement"><a class="anchor" href="#jboss-descriptor-property-replacement"></a><a class="link" href="#jboss-descriptor-property-replacement">JBoss Descriptor Property Replacement</a></h6>
<div class="paragraph">
<p>Flag indicating whether system property replacement will be performed on
WildFly proprietary XML descriptors, such as <code>jboss-app.xml</code>. This
defaults to <code>true</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;jboss-descriptor-property-replacement&gt;</span>false<span class="tag">&lt;/jboss-descriptor-property-replacement&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>When enabled, properties can be replaced in the following deployment descriptors:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>jboss-ejb3.xml</p>
</li>
<li>
<p>jboss-app.xml</p>
</li>
<li>
<p>jboss-web.xml</p>
</li>
<li>
<p>jboss-permissions.xml</p>
</li>
<li>
<p>*-jms.xml</p>
</li>
<li>
<p>*-ds.xml</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6 id="annotation-property-replacement"><a class="anchor" href="#annotation-property-replacement"></a><a class="link" href="#annotation-property-replacement">Annotation Property Replacement</a></h6>
<div class="paragraph">
<p>Flag indicating whether system property replacement will be performed on
Java annotations. The default value is <code>false</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;annotation-property-replacement&gt;</span>false<span class="tag">&lt;/annotation-property-replacement&gt;</span></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="EE_Concurrency_Utilities_Configuration"><a class="anchor" href="#EE_Concurrency_Utilities_Configuration"></a><a class="link" href="#EE_Concurrency_Utilities_Configuration">7.1.2. EE Concurrency Utilities</a></h4>
<div class="paragraph">
<p>EE Concurrency Utilities (JSR 236) were introduced to
ease the task of writing multithreaded applications. Instances
of these utilities are managed by WildFly, and the related configuration.</p>
</div>
<div class="sect4">
<h5 id="context-services"><a class="anchor" href="#context-services"></a><a class="link" href="#context-services">Context Services</a></h5>
<div class="paragraph">
<p>The Context Service is a concurrency utility which creates contextual
proxies from existent objects. WildFly Context Services are also used to
propagate the context from a Jakarta EE application invocation thread, to
the threads internally used by the other EE Concurrency Utilities.
Context Service instances may be created using the subsystem XML
configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;context-services&gt;</span>
    <span class="tag">&lt;context-service</span>
 <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/context/default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">use-transaction-setup-provider</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  <span class="tag">&lt;/context-services&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory, and it&#8217;s value should be a unique
name within all Context Services.</p>
</div>
<div class="paragraph">
<p>The <code>jndi-name</code> attribute is also mandatory, and defines where in the
JNDI the Context Service should be placed.</p>
</div>
<div class="paragraph">
<p>The optional <code>use-trasaction-setup-provider</code> attribute indicates if the
contextual proxies built by the Context Service should suspend
transactions in context, when invoking the proxy objects, and its value
defaults to true.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may also be used to
configure Context Service instances. An example to <code>add</code> and <code>remove</code>
one named <code>other</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/context-service=other:add(jndi-name=java\:jboss\/ee\/concurrency\/other)
/subsystem=ee/context-service=other:remove</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="managed-thread-factories"><a class="anchor" href="#managed-thread-factories"></a><a class="link" href="#managed-thread-factories">Managed Thread Factories</a></h5>
<div class="paragraph">
<p>The Managed Thread Factory allows Jakarta EE applications to create new
threads. WildFly Managed Thread Factory instances may also, optionally,
use a Context Service instance to propagate the Jakarta EE application
thread&#8217;s context to the new threads. Instance creation is done through
the EE subsystem, by editing the subsystem XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;managed-thread-factories&gt;</span>
    <span class="tag">&lt;managed-thread-factory</span>
 <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/factory/default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">priority</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  <span class="tag">&lt;/managed-thread-factories&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory, and it&#8217;s value should be a unique
name within all Managed Thread Factories.</p>
</div>
<div class="paragraph">
<p>The <code>jndi-name</code> attribute is also mandatory, and defines where in the
JNDI the Managed Thread Factory should be placed.</p>
</div>
<div class="paragraph">
<p>The optional <code>context-service</code> references an existent Context Service by
its <code>name</code>. If specified then thread created by the factory will
propagate the invocation context, present when creating the thread.</p>
</div>
<div class="paragraph">
<p>The optional <code>priority</code> indicates the priority for new threads created
by the factory, and defaults to <code>5</code>.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may also be used to
configure Managed Thread Factory instances. An example to <code>add</code> and
<code>remove</code> one named <code>other</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/managed-thread-factory=other:add(jndi-name=java\:jboss\/ee\/factory\/other)
/subsystem=ee/managed-thread-factory=other:remove</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="managed-executor-services"><a class="anchor" href="#managed-executor-services"></a><a class="link" href="#managed-executor-services">Managed Executor Services</a></h5>
<div class="paragraph">
<p>The Managed Executor Service is the Jakarta EE adaptation of Java SE
Executor Service, providing to Jakarta EE applications the functionality of
asynchronous task execution. WildFly is responsible to manage the
lifecycle of Managed Executor Service instances, which are specified
through the EE subsystem XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;managed-executor-services&gt;</span>
    <span class="tag">&lt;managed-executor-service</span>
        <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/executor/default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">hung-task-threshold</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">hung-task-termination-period</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">core-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">max-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">25</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">keepalive-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">queue-length</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1000000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">reject-policy</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">RETRY_ABORT</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/managed-executor-services&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory, and it&#8217;s value should be a unique
name within all Managed Executor Services.</p>
</div>
<div class="paragraph">
<p>The <code>jndi-name</code> attribute is also mandatory, and defines where in the
JNDI the Managed Executor Service should be placed.</p>
</div>
<div class="paragraph">
<p>The optional <code>context-service</code> references an existent Context Service by
its <code>name</code>. If specified then the referenced Context Service will
capture the invocation context present when submitting a task to the
executor, which will then be used when executing the task.</p>
</div>
<div class="paragraph">
<p>The optional <code>thread-factory</code> references an existent Managed Thread
Factory by its <code>name</code>, to handle the creation of internal threads. If
not specified then a Managed Thread Factory with default configuration
will be created and used internally.</p>
</div>
<div class="paragraph">
<p>The mandatory <code>core-threads</code> provides the number of threads to keep in
the executor&#8217;s pool, even if they are idle. If this is not defined or
is set to 0, the core pool size will be calculated based on the number
of available processors.</p>
</div>
<div class="paragraph">
<p>The optional <code>queue-length</code> indicates the number of tasks that can be
stored in the input queue. The default value is <code>0</code>, which means the
queue capacity is unlimited.</p>
</div>
<div class="paragraph">
<p>The executor&#8217;s task queue is based on the values of the attributes
<code>core-threads</code> and <code>queue-length</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If <code>queue-length</code> is <code>0</code>, or <code>queue-length</code> is
<code>Integer.MAX_VALUE (2147483647)</code> and <code>core-threads</code> is <code>0</code>, direct
handoff queuing strategy will be used and a synchronous queue will be
created.</p>
</li>
<li>
<p>If <code>queue-length</code> is <code>Integer.MAX_VALUE</code> but <code>core-threads</code> is not
<code>0</code>, an unbounded queue will be used.</p>
</li>
<li>
<p>For any other valid value for <code>queue-length</code>, a bounded queue wil be
created.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The optional <code>hung-task-threshold</code> defines a runtime threshold value, in
milliseconds, for tasks to be considered hung by the executor.
A value of <code>0</code> will never consider tasks to be hung.</p>
</div>
<div class="paragraph">
<p>The optional <code>hung-task-termination-period</code> defines the period, in
milliseconds, for attempting the termination of hung tasks, by cancelling
their execution, and interrupting their executing threads. Please note
that the termination of a cancelled hung task is not guaranteed.
A value of <code>0</code>, which is the default, deactivates the periodic
cancellation of hung tasks. Management clients, such as the WildFly CLI,
may still be used to manually attempt the termination of hung tasks:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/managed-executor-service=other:terminate-hung-tasks</code></pre>
</div>
</div>
<div class="paragraph">
<p>The optional <code>long-running-tasks</code> is a hint to optimize the execution of
long running tasks, and defaults to <code>false</code>.</p>
</div>
<div class="paragraph">
<p>The optional <code>max-threads</code> defines the the maximum number of threads
used by the executor, which defaults to Integer.MAX_VALUE (2147483647).</p>
</div>
<div class="paragraph">
<p>The optional <code>keepalive-time</code> defines the time, in milliseconds, that an
internal thread may be idle. The attribute default value is <code>60000</code>.</p>
</div>
<div class="paragraph">
<p>The optional reject-policy defines the policy to use when a task is
rejected by the executor. The attribute value may be the default
<code>ABORT</code>, which means an exception should be thrown, or <code>RETRY_ABORT</code>,
which means the executor will try to submit it once more, before
throwing an exception.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may also be used to
configure Managed Executor Service instances. An example to <code>add</code> and
<code>remove</code> one named <code>other</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/managed-executor-service=other:add(jndi-name=java\:jboss\/ee\/executor\/other, core-threads=2)
/subsystem=ee/managed-executor-service=other:remove</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="managed-scheduled-executor-services"><a class="anchor" href="#managed-scheduled-executor-services"></a><a class="link" href="#managed-scheduled-executor-services">Managed Scheduled Executor Services</a></h5>
<div class="paragraph">
<p>The Managed Scheduled Executor Service is the Jakarta EE adaptation of Java
SE Scheduled Executor Service, providing to Jakarta EE applications the
functionality of scheduling task execution. WildFly is responsible to
manage the lifecycle of Managed Scheduled Executor Service instances,
which are specified through the EE subsystem XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;managed-scheduled-executor-services&gt;</span>
    <span class="tag">&lt;managed-scheduled-executor-service</span>
        <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/scheduler/default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">hung-task-threshold</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">core-threads</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">keepalive-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">reject-policy</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">RETRY_ABORT</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/managed-scheduled-executor-services&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory, and it&#8217;s value should be a unique
name within all Managed Scheduled Executor Services.</p>
</div>
<div class="paragraph">
<p>The <code>jndi-name</code> attribute is also mandatory, and defines where in the
JNDI the Managed Scheduled Executor Service should be placed.</p>
</div>
<div class="paragraph">
<p>The optional <code>context-service</code> references an existent Context Service by
its <code>name</code>. If specified then the referenced Context Service will
capture the invocation context present when submitting a task to the
executor, which will then be used when executing the task.</p>
</div>
<div class="paragraph">
<p>The optional <code>thread-factory</code> references an existent Managed Thread
Factory by its <code>name</code>, to handle the creation of internal threads. If
not specified then a Managed Thread Factory with default configuration
will be created and used internally.</p>
</div>
<div class="paragraph">
<p>The mandatory <code>core-threads</code> provides the number of threads to keep in
the executor&#8217;s pool, even if they are idle. A value of <code>0</code> means there
is no limit.</p>
</div>
<div class="paragraph">
<p>The optional <code>hung-task-threshold</code> defines a runtime threshold value, in
milliseconds, for tasks to be considered hung by the executor.
A value of <code>0</code> will never consider tasks to be hung.</p>
</div>
<div class="paragraph">
<p>The optional <code>hung-task-termination-period</code> defines the period, in
milliseconds, for attempting the termination of hung tasks, by cancelling
their execution, and interrupting their executing threads. Please note
that the termination of a cancelled hung task is not guaranteed.
A value of <code>0</code>, which is the default, deactivates the periodic
cancellation of hung tasks. Management clients, such as the WildFly CLI,
may still be used to manually attempt the termination of hung tasks:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/managed-scheduled-executor-service=other:terminate-hung-tasks</code></pre>
</div>
</div>
<div class="paragraph">
<p>The optional <code>long-running-tasks</code> is a hint to optimize the execution of
long running tasks, and defaults to <code>false</code>.</p>
</div>
<div class="paragraph">
<p>The optional <code>keepalive-time</code> defines the time, in milliseconds, that an
internal thread may be idle. The attribute default value is <code>60000</code>.</p>
</div>
<div class="paragraph">
<p>The optional reject-policy defines the policy to use when a task is
rejected by the executor. The attribute value may be the default
<code>ABORT</code>, which means an exception should be thrown, or <code>RETRY_ABORT</code>,
which means the executor will try to submit it once more, before
throwing an exception.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may also be used to
configure Managed Scheduled Executor Service instances. An example to
<code>add</code> and <code>remove</code> one named <code>other</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=ee/managed-scheduled-executor-service=other:add(jndi-name=java\:jboss\/ee\/scheduler\/other, core-threads=2)
/subsystem=ee/managed-scheduled-executor-service=other:remove</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="EE_Default_Bindings_Configuration"><a class="anchor" href="#EE_Default_Bindings_Configuration"></a><a class="link" href="#EE_Default_Bindings_Configuration">7.1.3. Default EE Bindings</a></h4>
<div class="paragraph">
<p>The Jakarta EE Specification mandates the existence of a default instance
for each of the following resources:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Context Service</p>
</li>
<li>
<p>Datasource</p>
</li>
<li>
<p>Jakarta Messaging Connection Factory</p>
</li>
<li>
<p>Managed Executor Service</p>
</li>
<li>
<p>Managed Scheduled Executor Service</p>
</li>
<li>
<p>Managed Thread Factory</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The EE subsystem looks up the default instances from JNDI, using the
names in the default bindings configuration, before placing those in the
standard JNDI names, such as <code>java:comp/DefaultManagedExecutorService</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;default-bindings</span>
 <span class="attribute-name">context-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/context/default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">datasource</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleDS</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">jms-connection-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/DefaultJMSConnectionFactory</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">managed-executor-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/executor/default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">managed-scheduled-executor-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/scheduler/default</span><span class="delimiter">&quot;</span></span>
 <span class="attribute-name">managed-thread-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/ee/concurrency/factory/default</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Above bindings become application dependencies upon deployment. However in some cases
they might not be required or covered by non-default resources. In such case default binding could be:</p>
</div>
<div class="exampleblock result">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>rewriten - to point to user configured resource( :write-attribute(name=&#8230;&#8203;,value=&#8230;&#8203;) )</p>
</li>
<li>
<p>undefined - if there is no need for runtime dependency( :undefine-attribute(name=&#8230;&#8203;) )</p>
</li>
</ul>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The default bindings are optional, if the jndi name for a default
binding is not configured then the related resource will not be
available to Jakarta EE applications.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If default EE resources are not required and bindings do not point at them,
it is safe to remove or turn off default services.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Naming"><a class="anchor" href="#Naming"></a><a class="link" href="#Naming">7.2. Naming Subsystem Configuration</a></h3>
<div class="paragraph">
<p>The Naming subsystem provides the JNDI implementation on WildFly, and
its configuration allows to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>bind entries in global JNDI namespaces</p>
</li>
<li>
<p>turn off/on the remote JNDI interface</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The subsystem name is naming and this document covers Naming subsystem
version <code>2.0</code>, which XML namespace within WildFly XML configurations is
<code>urn:jboss:domain:naming:2.0</code>. The path for the subsystem&#8217;s XML schema,
within WildFly&#8217;s distribution, is <code>docs/schema/jboss-as-naming_2_0.xsd</code>.</p>
</div>
<div class="paragraph">
<p>Subsystem XML configuration example with all elements and attributes
specified:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:naming:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;bindings&gt;</span>
        <span class="tag">&lt;simple</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/a</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">int</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;simple</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/jboss.org/docs/url</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">https://docs.jboss.org</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.net.URL</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;object-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/foo/bar/factory</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar.ObjectFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;external-context</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/federation/ldap/example</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">javax.naming.directory.InitialDirContext</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">cache</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;environment&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.factory.initial</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.sun.jndi.ldap.LdapCtxFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.provider.url</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ldap://ldap.example.com:389</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.authentication</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.principal</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">uid=admin,ou=system</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.credentials</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;/environment&gt;</span>
        <span class="tag">&lt;/external-context&gt;</span>
        <span class="tag">&lt;lookup</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/c</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">lookup</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/b</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/bindings&gt;</span>
    <span class="tag">&lt;remote-naming</span><span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="Naming_Global_Bindings_Configuration"><a class="anchor" href="#Naming_Global_Bindings_Configuration"></a><a class="link" href="#Naming_Global_Bindings_Configuration">7.2.1. Global Bindings Configuration</a></h4>
<div class="paragraph">
<p>The Naming subsystem configuration allows binding entries into the
following global JNDI namespaces:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>java:global</code></p>
</li>
<li>
<p><code>java:jboss</code></p>
</li>
<li>
<p><code>java:</code></p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If WildFly is to be used as a Jakarta EE application server, then it&#8217;s
recommended to opt for <code>java:global</code>, since it is a standard (i.e.
portable) namespace.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Four different types of bindings are supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Simple</p>
</li>
<li>
<p>Object Factory</p>
</li>
<li>
<p>External Context</p>
</li>
<li>
<p>Lookup</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In the subsystem&#8217;s XML configuration, global bindings are configured
through the <code>&lt;bindings /&gt;</code> XML element, as an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;bindings&gt;</span>
    <span class="tag">&lt;simple</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/a</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">int</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;object-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/foo/bar/factory</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar.ObjectFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;external-context</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/federation/ldap/example</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">javax.naming.directory.InitialDirContext</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">cache</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;environment&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.factory.initial</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.sun.jndi.ldap.LdapCtxFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.provider.url</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ldap://ldap.example.com:389</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.authentication</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.principal</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">uid=admin,ou=system</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.credentials</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;/environment&gt;</span>
    <span class="tag">&lt;/external-context&gt;</span>
    <span class="tag">&lt;lookup</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/c</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">lookup</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/b</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/bindings&gt;</span></code></pre>
</div>
</div>
<div class="sect4">
<h5 id="simple-bindings"><a class="anchor" href="#simple-bindings"></a><a class="link" href="#simple-bindings">Simple Bindings</a></h5>
<div class="paragraph">
<p>A simple binding is a primitive or java.net.URL entry, and it is defined
through the <code>simple</code> XML element. An example of its XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;simple</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/a</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">int</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory and specifies the target JNDI name for
the entry.</p>
</div>
<div class="paragraph">
<p>The <code>value</code> attribute is mandatory and defines the entry&#8217;s value.</p>
</div>
<div class="paragraph">
<p>The optional <code>type</code> attribute, which defaults to <code>java.lang.String</code>,
specifies the type of the entry&#8217;s value. Besides java.lang.String,
allowed types are all the primitive types and their corresponding object
wrapper classes, such as int or java.lang.Integer, and java.net.URL.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may be used to configure
simple bindings. An example to <code>add</code> and <code>remove</code> the one in the XML
example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=naming/binding=java\:global\/a:add(binding-type=simple, type=int, value=100)
/subsystem=naming/binding=java\:global\/a:remove</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="object-factories"><a class="anchor" href="#object-factories"></a><a class="link" href="#object-factories">Object Factories</a></h5>
<div class="paragraph">
<p>The Naming subsystem configuration allows the binding of
<code>javax.naming.spi.ObjectFactory</code> entries, through the <code>object-factory</code>
XML element, for instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;object-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/foo/bar/factory</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.bar.ObjectFactory</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;environment&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">p1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">v1</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">p2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">v2</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/environment&gt;</span>
<span class="tag">&lt;/object-factory&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory and specifies the target JNDI name for
the entry.</p>
</div>
<div class="paragraph">
<p>The <code>class</code> attribute is mandatory and defines the object factory&#8217;s Java
type.</p>
</div>
<div class="paragraph">
<p>The <code>module</code> attribute is mandatory and specifies the JBoss Module ID
where the object factory Java class may be loaded from.</p>
</div>
<div class="paragraph">
<p>The optional <code>environment</code> child element may be used to provide a custom
environment to the object factory.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may be used to configure
object factory bindings. An example to <code>add</code> and <code>remove</code> the one in the
XML example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=naming/binding=java\:global\/foo\/bar\/factory:add(binding-type=object-factory, module=org.foo.bar, class=org.foo.bar.ObjectFactory, environment=[p1=v1, p2=v2])
/subsystem=naming/binding=java\:global\/foo\/bar\/factory:remove</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="external-context-federation"><a class="anchor" href="#external-context-federation"></a><a class="link" href="#external-context-federation">External Context Federation</a></h5>
<div class="paragraph">
<p>Federation of external JNDI contexts, such as a LDAP context, are
achieved by adding External Context bindings to the global bindings
configuration, through the <code>external-context</code> XML element. An example of
its XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;external-context</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/federation/ldap/example</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">javax.naming.directory.InitialDirContext</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">cache</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;environment&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.factory.initial</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.sun.jndi.ldap.LdapCtxFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.provider.url</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ldap://ldap.example.com:389</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.authentication</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.principal</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">uid=admin,ou=system</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.security.credentials</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/environment&gt;</span>
<span class="tag">&lt;/external-context&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory and specifies the target JNDI name for
the entry.</p>
</div>
<div class="paragraph">
<p>The <code>class</code> attribute is mandatory and indicates the Java initial naming
context type used to create the federated context. Note that such type
must have a constructor with a single environment map argument.</p>
</div>
<div class="paragraph">
<p>The optional <code>module</code> attribute specifies the JBoss Module ID where any
classes required by the external JNDI context may be loaded from.</p>
</div>
<div class="paragraph">
<p>The optional <code>cache</code> attribute, which value defaults to <code>false</code>,
indicates if the external context instance should be cached.</p>
</div>
<div class="paragraph">
<p>The optional <code>environment</code> child element may be used to provide the
custom environment needed to lookup the external context.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may be used to configure
external context bindings. An example to <code>add</code> and <code>remove</code> the one in
the XML example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=naming/binding=java\:global\/federation\/ldap\/example:add(binding-type=external-context, cache=true, class=javax.naming.directory.InitialDirContext, environment=[java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap\:\/\/ldap.example.com\:389, java.naming.security.authentication=simple, java.naming.security.principal=uid\=admin\,ou\=system, java.naming.security.credentials= secret])
 
/subsystem=naming/binding=java\:global\/federation\/ldap\/example:remove</code></pre>
</div>
</div>
<div class="paragraph">
<p>Some JNDI providers may fail when their resources are looked up if they
do not implement properly the lookup(Name) method. Their errors would
look like:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 100%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">11:31:49,047 ERROR org.jboss.resource.adapter.jms.inflow.JmsActivation
(default-threads -1) javax.naming.InvalidNameException: Only support
CompoundName namesat
com.tibco.tibjms.naming.TibjmsContext.lookup(TibjmsContext.java:504)at
javax.naming.InitialContext.lookup(InitialContext.java:421)</th>
</tr>
</thead>
</table>
<div class="paragraph">
<p>To work around their shortcomings, the
<code>org.jboss.as.naming.lookup.by.string</code> property can be specified in the
external-context&#8217;s environment to use instead the lookup(String) method
(with a performance degradation):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.naming.lookup.by.string</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Binding Aliases</strong></p>
</div>
<div class="paragraph">
<p>The Naming subsystem configuration allows the binding of existent
entries into additional names, i.e. aliases. Binding aliases are
specified through the <code>lookup</code> XML element. An example of its XML
configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;lookup</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/c</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">lookup</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/b</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code> attribute is mandatory and specifies the target JNDI name for
the entry.</p>
</div>
<div class="paragraph">
<p>The <code>lookup</code> attribute is mandatory and indicates the source JNDI name.
It can chain lookups on external contexts. For example, having an
external context bounded to <em>java:global/federation/ldap/example</em>,
searching can be done there by setting <code>lookup</code> attribute to
<em>java:global/federation/ldap/example/subfolder</em>.</p>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may be used to configure
binding aliases. An example to <code>add</code> and <code>remove</code> the one in the XML
example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=naming/binding=java\:global\/c:add(binding-type=lookup, lookup=java\:global\/b)
/subsystem=naming/binding=java\:global\/c:remove</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Naming_Remote_JNDI_Configuration"><a class="anchor" href="#Naming_Remote_JNDI_Configuration"></a><a class="link" href="#Naming_Remote_JNDI_Configuration">7.2.2. Remote JNDI Configuration</a></h4>
<div class="paragraph">
<p>The Naming subsystem configuration may be used to (de)activate the
remote JNDI interface, which allows clients to lookup entries present in
a remote WildFly instance.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Only entries within the <code>java:jboss/exported</code> context are accessible
over remote JNDI.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In the subsystem&#8217;s XML configuration, remote JNDI access bindings are
configured through the <code>&lt;remote-naming /&gt;</code> XML element:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;remote-naming</span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Management clients, such as the WildFly CLI, may be used to add/remove
the remote JNDI interface. An example to <code>add</code> and <code>remove</code> the one in
the XML example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=naming/service=remote-naming:add
/subsystem=naming/service=remote-naming:remove</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="DataSource"><a class="anchor" href="#DataSource"></a><a class="link" href="#DataSource">7.3. DataSource configuration</a></h3>
<div class="paragraph">
<p>Datasources are configured through the <em>datasource</em> subsystem. Declaring
a new datasource consists of two separate steps: You would need to
provide a JDBC driver and define a datasource that references the driver
you installed.</p>
</div>
<div class="sect3">
<h4 id="jdbc-driver-installation"><a class="anchor" href="#jdbc-driver-installation"></a><a class="link" href="#jdbc-driver-installation">7.3.1. JDBC Driver Installation</a></h4>
<div class="paragraph">
<p>The recommended way to install a JDBC driver into WildFly 27 is to deploy
it as a regular JAR deployment. The reason for this is that when you run
WildFly in domain mode, deployments are automatically propagated to all
servers to which the deployment applies; thus distribution of the driver
JAR is one less thing for you to worry about!</p>
</div>
<div class="paragraph">
<p>Any JDBC 4-compliant driver will automatically be recognized and
installed into the system by name and version. A JDBC JAR is identified
using the Java service provider mechanism. Such JARs will contain a text
a file named <code>META-INF/services/java.sql.Driver</code>, which contains the
name of the class(es) of the Drivers which exist in that JAR. If your
JDBC driver JAR is not JDBC 4-compliant, it can be made deployable in
one of a few ways.</p>
</div>
<div class="paragraph">
<p><strong>Modify the JAR</strong></p>
</div>
<div class="paragraph">
<p>The most straightforward solution is to simply modify the JAR and add
the missing file. You can do this from your command shell by:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Change to, or create, an empty temporary directory.</p>
</li>
<li>
<p>Create a <code>META-INF</code> subdirectory.</p>
</li>
<li>
<p>Create a <code>META-INF/services</code> subdirectory.</p>
</li>
<li>
<p>Create a <code>META-INF/services/java.sql.Driver</code> file which contains one
line - the fully-qualified class name of the JDBC driver.</p>
</li>
<li>
<p>Use the <code>jar</code> command-line tool to update the JAR like this:</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver</code></pre>
</div>
</div>
<div class="paragraph">
<p>For a detailed explanation how to deploy JDBC 4 compliant driver jar,
please refer to the chapter " <a href="#application-deployment">Application Deployment</a>".</p>
</div>
</div>
<div class="sect3">
<h4 id="datasource-definitions"><a class="anchor" href="#datasource-definitions"></a><a class="link" href="#datasource-definitions">7.3.2. Datasource Definitions</a></h4>
<div class="paragraph">
<p>The datasource itself is defined within the subsystem <em>datasources</em>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources:4.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;datasources&gt;</span>
        <span class="tag">&lt;datasource</span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleDS</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ExampleDS</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;connection-url&gt;</span>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1<span class="tag">&lt;/connection-url&gt;</span>
            <span class="tag">&lt;driver&gt;</span>h2<span class="tag">&lt;/driver&gt;</span>
            <span class="tag">&lt;pool&gt;</span>
                <span class="tag">&lt;min-pool-size&gt;</span>10<span class="tag">&lt;/min-pool-size&gt;</span>
                <span class="tag">&lt;max-pool-size&gt;</span>20<span class="tag">&lt;/max-pool-size&gt;</span>
                <span class="tag">&lt;prefill&gt;</span>true<span class="tag">&lt;/prefill&gt;</span>
            <span class="tag">&lt;/pool&gt;</span>
            <span class="tag">&lt;security&gt;</span>
                <span class="tag">&lt;user-name&gt;</span>sa<span class="tag">&lt;/user-name&gt;</span>
                <span class="tag">&lt;password&gt;</span>sa<span class="tag">&lt;/password&gt;</span>
            <span class="tag">&lt;/security&gt;</span>
        <span class="tag">&lt;/datasource&gt;</span>
        <span class="tag">&lt;xa-datasource</span><span class="error"> </span><span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleXADS</span><span class="delimiter">&quot;</span></span><span class="error"> </span><span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ExampleXADS</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;driver&gt;</span>h2<span class="tag">&lt;/driver&gt;</span>
           <span class="tag">&lt;xa-datasource-property</span><span class="error"> </span><span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">URL</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>jdbc:h2:mem:test<span class="tag">&lt;/xa-datasource-property&gt;</span>
           <span class="tag">&lt;xa-pool&gt;</span>
                <span class="tag">&lt;min-pool-size&gt;</span>10<span class="tag">&lt;/min-pool-size&gt;</span>
                <span class="tag">&lt;max-pool-size&gt;</span>20<span class="tag">&lt;/max-pool-size&gt;</span>
                <span class="tag">&lt;prefill&gt;</span>true<span class="tag">&lt;/prefill&gt;</span>
           <span class="tag">&lt;/xa-pool&gt;</span>
           <span class="tag">&lt;security&gt;</span>
                <span class="tag">&lt;user-name&gt;</span>sa<span class="tag">&lt;/user-name&gt;</span>
                <span class="tag">&lt;password&gt;</span>sa<span class="tag">&lt;/password&gt;</span>
           <span class="tag">&lt;/security&gt;</span>
        <span class="tag">&lt;/xa-datasource&gt;</span>
        <span class="tag">&lt;drivers&gt;</span>
            <span class="tag">&lt;driver</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">h2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.h2database.h2</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;xa-datasource-class&gt;</span>org.h2.jdbcx.JdbcDataSource<span class="tag">&lt;/xa-datasource-class&gt;</span>
            <span class="tag">&lt;/driver&gt;</span>
        <span class="tag">&lt;/drivers&gt;</span>
  <span class="tag">&lt;/datasources&gt;</span>
 
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><sub>(See</sub> <code>standalone/configuration/standalone.xml</code> <sub>)</sub></p>
</div>
<div class="paragraph">
<p>As you can see the datasource references a driver by it&#8217;s logical name.</p>
</div>
<div class="paragraph">
<p>You can easily query the same information through the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=datasources:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;data-source&quot; =&gt; {&quot;H2DS&quot; =&gt; {
            &quot;connection-url&quot; =&gt; &quot;jdbc:h2:mem:test;DB_CLOSE_DELAY=-1&quot;,
            &quot;jndi-name&quot; =&gt; &quot;java:/H2DS&quot;,
            &quot;driver-name&quot; =&gt; &quot;h2&quot;,
            &quot;pool-name&quot; =&gt; &quot;H2DS&quot;,
            &quot;use-java-context&quot; =&gt; true,
            &quot;enabled&quot; =&gt; true,
            &quot;jta&quot; =&gt; true,
            &quot;pool-prefill&quot; =&gt; true,
            &quot;pool-use-strict-min&quot; =&gt; false,
            &quot;user-name&quot; =&gt; &quot;sa&quot;,
            &quot;password&quot; =&gt; &quot;sa&quot;,
            &quot;flush-strategy&quot; =&gt; &quot;FailingConnectionOnly&quot;,
            &quot;background-validation&quot; =&gt; false,
            &quot;use-fast-fail&quot; =&gt; false,
            &quot;validate-on-match&quot; =&gt; false,
            &quot;use-ccm&quot; =&gt; true
        }},
        &quot;xa-data-source&quot; =&gt; undefined,
        &quot;jdbc-driver&quot; =&gt; {&quot;h2&quot; =&gt; {
            &quot;driver-name&quot; =&gt; &quot;h2&quot;,
            &quot;driver-module-name&quot; =&gt; &quot;com.h2database.h2&quot;,
            &quot;driver-xa-datasource-class-name&quot; =&gt; &quot;org.h2.jdbcx.JdbcDataSource&quot;
        }}
    }
}
 
 
[standalone@localhost:9990 /] /subsystem=datasources:installed-drivers-list
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [{
        &quot;driver-name&quot; =&gt; &quot;h2&quot;,
        &quot;datasource-class-info&quot; =&gt; [{&quot;org.h2.jdbcx.JdbcDataSource&quot; =&gt; {
            &quot;URL&quot; =&gt; &quot;java.lang.String&quot;,
            &quot;description&quot; =&gt; &quot;java.lang.String&quot;,
            &quot;loginTimeout&quot; =&gt; &quot;int&quot;,
            &quot;password&quot; =&gt; &quot;java.lang.String&quot;,
            &quot;url&quot; =&gt; &quot;java.lang.String&quot;,
            &quot;user&quot; =&gt; &quot;java.lang.String&quot;
        }}],
        &quot;deployment-name&quot; =&gt; undefined,
        &quot;driver-module-name&quot; =&gt; &quot;com.h2database.h2&quot;,
        &quot;module-slot&quot; =&gt; &quot;main&quot;,
        &quot;driver-xa-datasource-class-name&quot; =&gt; &quot;org.h2.jdbcx.JdbcDataSource&quot;,
        &quot;driver-class-name&quot; =&gt; &quot;org.h2.Driver&quot;,
        &quot;driver-major-version&quot; =&gt; 1,
        &quot;driver-minor-version&quot; =&gt; 3,
        &quot;jdbc-compliant&quot; =&gt; true
    }]
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<code>datasource-class-info</code> shows connection properties defined in the <code>(xa-)datasource-class</code>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Using the web console or the CLI greatly simplifies the deployment of
JDBC drivers and the creation of datasources.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The CLI offers a set of commands to create and modify datasources:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] data-source --help
 
SYNOPSIS
  data-source --help [--properties | --commands] |
              (--name=&lt;resource_id&gt; (--&lt;property&gt;=&lt;value&gt;)*) |
              (&lt;command&gt; --name=&lt;resource_id&gt; (--&lt;parameter&gt;=&lt;value&gt;)*)
              [--headers={&lt;operation_header&gt; (;&lt;operation_header&gt;)*}]
DESCRIPTION
  The command is used to manage resources of type /subsystem=datasources/data-source.
[...]
 
 
[standalone@localhost:9990 /] xa-data-source --help
 
SYNOPSIS
  xa-data-source --help [--properties | --commands] |
                 (--name=&lt;resource_id&gt; (--&lt;property&gt;=&lt;value&gt;)*) |
                 (&lt;command&gt; --name=&lt;resource_id&gt; (--&lt;parameter&gt;=&lt;value&gt;)*)
                 [--headers={&lt;operation_header&gt; (;&lt;operation_header&gt;)*}]
 
DESCRIPTION
  The command is used to manage resources of type /subsystem=datasources/xa-data-source.
 
RESOURCE DESCRIPTION
  A JDBC XA data-source configuration
 
[...]</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="ds-component-reference"><a class="anchor" href="#ds-component-reference"></a><a class="link" href="#ds-component-reference">7.3.3. Component Reference</a></h4>
<div class="paragraph">
<p>The datasource subsystem is provided by the
<a href="http://www.jboss.org/ironjacamar">IronJacamar</a> project. For a detailed
description of the available configuration properties, please consult
the project documentation.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>IronJacamar homepage: <a href="http://ironjacamar.org/" class="bare">http://ironjacamar.org/</a></p>
</li>
<li>
<p>Project Documentation: <a href="http://ironjacamar.org/documentation.html" class="bare">http://ironjacamar.org/documentation.html</a></p>
</li>
<li>
<p>Schema description:
<a href="http://www.ironjacamar.org/doc/userguide/1.1/en-US/html_single/index.html#deployingds_descriptor" class="bare">http://www.ironjacamar.org/doc/userguide/1.1/en-US/html_single/index.html#deployingds_descriptor</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="agroal"><a class="anchor" href="#agroal"></a><a class="link" href="#agroal">7.4. Agroal configuration</a></h3>
<div class="paragraph">
<p>The Agroal subsystem allows the definition of datasources. Declaring a new datasource consists of two separate steps: provide a JDBC driver and define a datasource that references the driver you installed.</p>
</div>
<div class="paragraph">
<p>The Agroal subsystem is provided by the <a href="https://agroal.github.io/">Agroal</a> project. For a detailed description of the available configuration properties, please consult the project documentation.</p>
</div>
<div class="sect3">
<h4 id="agroal-subssystem-enable"><a class="anchor" href="#agroal-subssystem-enable"></a><a class="link" href="#agroal-subssystem-enable">7.4.1. Enabling the subsystem</a></h4>
<div class="paragraph">
<p>If the WildFly configuration does not have Agroal subsystem enabled by default, it can be enabled in the following ways.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extensions&gt;</span>
    <span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.wildfly.extension.datasources-agroal</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    [...]
<span class="tag">&lt;/extensions&gt;</span>
<span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources-agroal:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    [...]
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990  /] /extension=org.wildfly.extension.datasources-agroal:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}
[standalone@localhost:9990  /] /subsystem=datasources-agroal:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="agroal-driver-installation"><a class="anchor" href="#agroal-driver-installation"></a><a class="link" href="#agroal-driver-installation">7.4.2. JDBC Driver Installation</a></h4>
<div class="paragraph">
<p>A driver definition is a reference to a class in a JDBC driver. Multiple definitions can be created on the same JDBC driver for multiple classes in it. Agroal requires an implementation of java.sql.Driver or javax.sql.DataSource for non-XA datasources, while for XA a javax.sql.XADataSource implementation is required.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Agroal will try to load an java.sql.Driver from the specified module if the <em>class</em> is not defined
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Any installed <em>driver</em> provides an operation called <em>class-info</em> that lists all the properties available for that particular class, that can be set in the <em>connection-factory</em>.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources-agroal:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    [...]
    <span class="tag">&lt;drivers&gt;</span>
        <span class="tag">&lt;driver</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">h2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.h2database.h2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.h2.Driver</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/drivers&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990  /] /subsystem=datasources-agroal/driver=h2:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;class&quot; =&gt; &quot;org.h2.Driver&quot;,
        &quot;module&quot; =&gt; &quot;com.h2database.h2&quot;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="agroal-common-datasource-definitions"><a class="anchor" href="#agroal-common-datasource-definitions"></a><a class="link" href="#agroal-common-datasource-definitions">7.4.3. Common Datasource Definitions</a></h4>
<div class="paragraph">
<p>Agroal provides both XA and non-XA datasources and most of the attributes that define them are common. This definition is mainly split in two logical units: the <em>connection factory</em> and the <em>connection pool</em>. As the name implies, the <em>connection factory</em> has all that is required to create new connections and <em>connection pool</em> defines how connections are handled by the pool.</p>
</div>
<div class="sect4">
<h5 id="agroal-connection-factory"><a class="anchor" href="#agroal-connection-factory"></a><a class="link" href="#agroal-connection-factory">Connection Factory definition</a></h5>
<div class="paragraph">
<p>The <em>connection factory</em> requires a reference to a <em>driver</em> (see <a href="#">agroal-driver-installation</a>). With a java.sql.Driver the preferred way to 'point' to the database is to specify an <em>url</em> attribute while for javax.sql.DataSource and javax.sql.XADataSource the preferred way is to specify <em>connection-properties</em>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Attributes <em>username</em> and <em>password</em> are provided for basic authentication with the database. Agroal does not allow <em>username</em> and <em>password</em> to be set as <em>connection-properties</em> due to security requirements.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Other features provided by the <em>connection-factory</em> definition include the possibility of executing a SQL statement right after the connection has been created and to specify the isolation level of transactions in the database.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources-agroal:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
     <span class="tag">&lt;datasource</span> <span class="error">[</span><span class="attribute-name">...</span><span class="error">]</span><span class="tag">&gt;</span>
        [...]
        <span class="tag">&lt;connection-factory</span> <span class="attribute-name">driver</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">h2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">url</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jdbc:h2:tcp://localhost:1701</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">transaction-isolation</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SERIALIZABLE</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">new-connection-sql</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">SELECT 1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">username</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sa</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sa</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;connection-properties&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">aProperty</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">aValue</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
                <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">anotherProperty</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">anotherValue</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;/connection-properties&gt;</span>
        <span class="tag">&lt;/connection-factory&gt;</span>
    <span class="tag">&lt;/datasource&gt;</span>
    [...]
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>---
[standalone@localhost:9990  /] /subsystem=datasources-agroal/datasource=sample:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;connection-factory&quot; =&gt; {
            &quot;driver&quot; =&gt; &quot;h2&quot;,
            &quot;url&quot; =&gt; &quot;jdbc:h2:tcp://localhost:1701&quot;,
            &quot;transaction-isolation&quot; =&gt; &quot;SERIALIZABLE&quot;,
            &quot;new-connection-sql&quot; =&gt; &quot;SELECT 1&quot;,
            &quot;username&quot; =&gt; &quot;sa&quot;,
            &quot;password&quot; =&gt; &quot;sa&quot;,
            &quot;connection-properties&quot; =&gt; {
                &quot;aProperty&quot; =&gt; &quot;aValue&quot;,
                &quot;anotherProperty&quot; =&gt; &quot;anotherValue&quot;
            }
        }
        [...]
    }
}
---</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="agroal-connection-pool"><a class="anchor" href="#agroal-connection-pool"></a><a class="link" href="#agroal-connection-pool">Connection Pool definition</a></h5>
<div class="paragraph">
<p>The main attributes of the <em>connection-pool</em> definition are the ones that control it&#8217;s size. While the <em>initial size</em> attribute is only taken into account while bootstrapping the pool, <em>min size</em> and <em>max size</em> are always enforced and can be changed at any time without requiring a reload of the server.</p>
</div>
<div class="paragraph">
<p>Another important attribute of the <em>connection-pool</em> is the <em>blocking timeout</em> that defines the maximum amount of time a thread will wait for a connection. If that time elapses and still no connection is available an exception is thrown. Keep in mind that the default value is <em>0</em>, meaning that a thread will wait forever for a connection to become available. Changing this setting does not require a reload of the server.</p>
</div>
<div class="paragraph">
<p>The <em>connection pool</em> provides other convenient features like background validation of connections on the pool, removal of idle connections from the pool and detection of connections held for too long by one thread. All these features are disabled by default and can be enabled by specifying an interval of time on the corresponding attribute.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
There is a set of flush operations that perform many of these features on-demand. These are <em>flush-all</em> to close all connections immediately, <em>flush-graceful</em> to close all connections under normal operation, <em>flush-invalid</em> to remove any invalid connections from the pool and <em>flush-idle</em> to remove any connections not being used.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources-agroal:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
     <span class="tag">&lt;datasource</span> <span class="error">[</span><span class="attribute-name">...</span><span class="error">]</span><span class="tag">&gt;</span>
        [...]
        <span class="tag">&lt;connection-pool</span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">30</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">min-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">initial-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">20</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">blocking-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">background-validation</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">6000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">leak-detection</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">idle-removal</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/datasource&gt;</span>
    [...]
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>---
[standalone@localhost:9990  /] /subsystem=datasources-agroal/datasource=sample:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;connection-pool&quot; =&gt; {
            &quot;max-size&quot; =&gt; 30,
            &quot;min-size&quot; =&gt; 10,
            &quot;initial-size&quot; =&gt; 20,
            &quot;blocking-timeout&quot; =&gt; 1000,
            &quot;background-validation&quot; =&gt; 6000,
            &quot;leak-detection&quot; =&gt; 5000,
            &quot;idle-removal&quot; =&gt; 5
        }
        [...]
    }
}
---</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="agroal-common-attributes"><a class="anchor" href="#agroal-common-attributes"></a><a class="link" href="#agroal-common-attributes">Common datasource attributes</a></h5>
<div class="paragraph">
<p>All datasources in Agroal have a name that&#8217;s used to locate them in the WildFly runtime model and are bound to a JNDI name.</p>
</div>
<div class="paragraph">
<p>The attribute <em>statistics-enabled</em> allow the collection of metrics regarding the pool that can be queried in the runtime model</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
There is also a <em>reset-statistics</em> operation provided.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:agroal:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;xa-datasource</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sample-xa</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleXADS</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">statistics-enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        [...]
    <span class="tag">&lt;/xa-datasource&gt;</span>
    [...]
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>---
[standalone@localhost:9990  /] /subsystem=datasources-agroal/datasource=sample-xa:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;jndi-name&quot; =&gt; &quot;java:jboss/datasources/ExampleXADS&quot;,
        &quot;statistics-enabled&quot; =&gt; true
        [...]
    }
}
---</code></pre>
</div>
</div>
<div class="paragraph">
<p>The available statistics include the number of created / destroyed connections and the number of connections in use / available in the pool. There are also statistics for the time it takes to create a connection and for how long have threads been blocked waiting for a connection.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990  /] /subsystem=datasources-agroal/datasource=sample:read-resource(include-runtime)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;statistics&quot; =&gt; {
            &quot;acquire-count&quot; =&gt; 10L,
            &quot;active-count&quot; =&gt; 3L,
            &quot;available-count&quot; =&gt; 17L,
            &quot;awaiting-count&quot; =&gt; 0L,
            &quot;creation-count&quot; =&gt; 20L,
            &quot;destroy-count&quot; =&gt; 0L,
            &quot;flush-count&quot; =&gt; 0L,
            &quot;invalid-count&quot; =&gt; 0L,
            &quot;leak-detection-count&quot; =&gt; 0L,
            &quot;max-used-count&quot; =&gt; 20L,
            &quot;reap-count&quot; =&gt; 0L,
            &quot;blocking-time-average-ms&quot; =&gt; 0L,
            &quot;blocking-time-max-ms&quot; =&gt; 0L,
            &quot;blocking-time-total-ms&quot; =&gt; 0L,
            &quot;creation-time-average-ms&quot; =&gt; 96L,
            &quot;creation-time-max-ms&quot; =&gt; 815L,
            &quot;creation-time-total-ms&quot; =&gt; 964L
        }
        [...]
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="agroal-datasource-attributes"><a class="anchor" href="#agroal-datasource-attributes"></a><a class="link" href="#agroal-datasource-attributes">DataSource specific attributes</a></h5>
<div class="paragraph">
<p>In addition to all the common attributes, a <em>datasource</em> definition may disable the Jakarta Transactions integration.</p>
</div>
<div class="paragraph">
<p>Deferred enlistment is not supported, meaning that if Jakarta Transactions is enabled a connection must always be obtained within the scope of a transaction. The connection will always be enlisted with that transaction (lazy enlistment is not supported).</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <em>connectable</em> attribute allows a non-XA datasource to take part in an XA transaction ('Last Resource Commit Optimization (LRCO)' / 'Commit Markable Resource')
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:datasources-agroal:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;datasource</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sample</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ExampleDS</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">jta</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">connectable</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">statistics-enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        [...]
    <span class="tag">&lt;/datasource&gt;</span>
    [...]
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>---
[standalone@localhost:9990  /] /subsystem=datasources-agroal/datasource=sample-xa:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;connectable&quot; =&gt; false,
        &quot;jta&quot; =&gt; false,
        [...]
    }
}
---</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="agroal-xa-datasource-attributes"><a class="anchor" href="#agroal-xa-datasource-attributes"></a><a class="link" href="#agroal-xa-datasource-attributes">XADataSource specific attributes</a></h5>
<div class="paragraph">
<p>At the moment there are no attributes specific to a XADataSource definition.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="agroal-known-limits"><a class="anchor" href="#agroal-known-limits"></a><a class="link" href="#agroal-known-limits">7.4.4. Agroal known limitations</a></h4>
<div class="paragraph">
<p>The subsystem to define default datasources remains "datasources" at the moment.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Logging"><a class="anchor" href="#Logging"></a><a class="link" href="#Logging">7.5. Logging Configuration</a></h3>
<div class="quoteblock abstract">
<blockquote>
The overall server logging configuration is represented by the logging
subsystem. It consists of four notable parts: <code>handler</code> configurations,
<code>logger</code>, the <code>root logger</code> declarations (aka log categories) and
logging profiles. Each logger does reference a handler (or set of
handlers). Each handler declares the log format and output:
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:logging:3.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;console-handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">CONSOLE</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">autoflush</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;level</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">DEBUG</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;formatter&gt;</span>
           <span class="tag">&lt;named-formatter</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">COLOR-PATTERN</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/formatter&gt;</span>
   <span class="tag">&lt;/console-handler&gt;</span>
   <span class="tag">&lt;periodic-rotating-file-handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">autoflush</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;formatter&gt;</span>
           <span class="tag">&lt;named-formatter</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">PATTERN</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/formatter&gt;</span>
       <span class="tag">&lt;file</span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.log.dir</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server.log</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;suffix</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">.yyyy-MM-dd</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/periodic-rotating-file-handler&gt;</span>
   <span class="tag">&lt;logger</span> <span class="attribute-name">category</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.arjuna</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;level</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">WARN</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/logger&gt;</span>
   [...]
   <span class="tag">&lt;root-logger&gt;</span>
       <span class="tag">&lt;level</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">DEBUG</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;handlers&gt;</span>
           <span class="tag">&lt;handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">CONSOLE</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
           <span class="tag">&lt;handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/handlers&gt;</span>
   <span class="tag">&lt;/root-logger&gt;</span>
   <span class="tag">&lt;formatter</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">PATTERN</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;pattern-formatter</span> <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/formatter&gt;</span>
   <span class="tag">&lt;formatter</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">COLOR-PATTERN</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;pattern-formatter</span> <span class="attribute-name">pattern</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/formatter&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="logging-attributes"><a class="anchor" href="#logging-attributes"></a><a class="link" href="#logging-attributes">7.5.1. Attributes</a></h4>
<div class="paragraph">
<p>The root resource contains two notable attributes
<code>add-logging-api-dependencies</code> and <code>use-deployment-logging-config</code>.</p>
</div>
<div class="sect4">
<h5 id="add-logging-api-dependencies"><a class="anchor" href="#add-logging-api-dependencies"></a><a class="link" href="#add-logging-api-dependencies">add-logging-api-dependencies</a></h5>
<div class="paragraph">
<p>The <code>add-logging-api-dependencies</code> controls whether or not the container
adds
<a href="Implicit_module_dependencies_for_deployments.html#src-557203_safe-id-SW1wbGljaXRtb2R1bGVkZXBlbmRlbmNpZXNmb3JkZXBsb3ltZW50cy1JbXBsaWNpdG1vZHVsZWRlcGVuZGVuY2llc2ZvcmRlcGxveW1lbnRzLVdoaWNoYXJldGhlaW1wbGljaXRtb2R1bGVkZXBlbmRlbmNpZXMlM0Y">implicit</a>
logging API dependencies to your deployments. If set to <code>true</code>, the
default, all the implicit logging API dependencies are added. If set to
<code>false</code> the dependencies are not added to your deployments.</p>
</div>
</div>
<div class="sect4">
<h5 id="use-deployment-logging-config"><a class="anchor" href="#use-deployment-logging-config"></a><a class="link" href="#use-deployment-logging-config">use-deployment-logging-config</a></h5>
<div class="paragraph">
<p>The <code>use-deployment-logging-config</code> controls whether or not your
deployment is scanned for
<a href="#per-deployment-logging">per-deployment
logging</a>. If set to <code>true</code>, the default,
<a href="#per-deployment-logging">per-deployment
logging</a> is enabled. Set to <code>false</code> to disable this feature.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="per-deployment-logging"><a class="anchor" href="#per-deployment-logging"></a><a class="link" href="#per-deployment-logging">7.5.2. Per-deployment Logging</a></h4>
<div class="paragraph">
<p>Per-deployment logging allows you to add a logging configuration file to
your deployment and have the logging for that deployment configured
according to the configuration file. In an EAR the configuration should
be in the <code>META-INF</code> directory. In a WAR or JAR deployment the
configuration file can be in either the <code>META-INF</code> or <code>WEB-INF/classes</code>
directories.</p>
</div>
<div class="paragraph">
<p>The following configuration files are allowed:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>logging.properties</p>
</li>
<li>
<p>jboss-logging.properties</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can also disable this functionality by changing the
<code>use-deployment-logging-config</code> attribute to <code>false</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="logging-profiles"><a class="anchor" href="#logging-profiles"></a><a class="link" href="#logging-profiles">7.5.3. Logging Profiles</a></h4>
<div class="paragraph">
<p>Logging profiles are like additional logging subsystems. Each logging
profile constists of three of the four notable parts listed above:
<code>handler</code> configurations, <code>logger</code> and the <code>root logger</code> declarations.</p>
</div>
<div class="paragraph">
<p>You can assign a logging profile to a deployment via the deployments
manifest. Add a <code>Logging-Profile</code> entry to the <code>MANIFEST.MF</code> file with a
value of the logging profile id. For example a logging profile defined
on <code>/subsystem=logging/logging-profile=ejbs</code> the MANIFEST.MF would look
like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Manifest-Version: 1.0
Logging-Profile: ejbs</pre>
</div>
</div>
<div class="paragraph">
<p>A logging profile can be assigned to any number of deployments. Using a
logging profile also allows for runtime changes to the configuration.
This is an advantage over the per-deployment logging configuration as
the redeploy is not required for logging changes to take affect.</p>
</div>
</div>
<div class="sect3">
<h4 id="default-log-file-locations"><a class="anchor" href="#default-log-file-locations"></a><a class="link" href="#default-log-file-locations">7.5.4. Default Log File Locations</a></h4>
<div class="sect4">
<h5 id="logging-managed-domain"><a class="anchor" href="#logging-managed-domain"></a><a class="link" href="#logging-managed-domain">Managed Domain</a></h5>
<div class="paragraph">
<p>In a managed domain two types of log files do exist: Controller and
server logs. The controller components govern the domain as whole. It&#8217;s
their responsibility to start/stop server instances and execute managed
operations throughout the domain. Server logs contain the logging
information for a particular server instance. They are co-located with
the host the server is running on.</p>
</div>
<div class="paragraph">
<p>For the sake of simplicity we look at the default setup for managed
domain. In this case, both the domain controller components and the
servers are located on the same host:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Process</th>
<th class="tableblock halign-left valign-top">Log File</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Host Controller</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./domain/log/host-controller.log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Process Controller</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./domain/log/process-controller.log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">"Server One"</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./domain/servers/server-one/log/server.log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">"Server Two"</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./domain/servers/server-two/log/server.log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">"Server Three"</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./domain/servers/server-three/log/server.log</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="logging-standalone-server"><a class="anchor" href="#logging-standalone-server"></a><a class="link" href="#logging-standalone-server">Standalone Server</a></h5>
<div class="paragraph">
<p>The default log files for a standalone server can be found in the log
subdirectory of the distribution:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Process</th>
<th class="tableblock halign-left valign-top">Log File</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Server</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">./standalone/log/server.log</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="list-log-files-and-reading-log-files"><a class="anchor" href="#list-log-files-and-reading-log-files"></a><a class="link" href="#list-log-files-and-reading-log-files">7.5.5. List Log Files and Reading Log Files</a></h4>
<div class="paragraph">
<p>Log files can be listed and viewed via management operations. The log
files allowed to be viewed are intentionally limited to files that exist
in the <code>jboss.server.log.dir</code> and are associated with a known file
handler. Known file handler types include <code>file-handler</code>,
<code>periodic-rotating-file-handler</code> and <code>size-rotating-file-handler</code>. The
operations are valid in both standalone and domain modes.</p>
</div>
<div class="sect4">
<h5 id="list-log-files"><a class="anchor" href="#list-log-files"></a><a class="link" href="#list-log-files">List Log Files</a></h5>
<div class="paragraph">
<p>The logging subsystem has a <code>log-file</code> resource off the subsystem root
resource and off each <code>logging-profile</code> resource to list each log file.</p>
</div>
<div class="listingblock">
<div class="title">CLI command and output</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=logging:read-children-names(child-type=log-file)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        &quot;server.log&quot;,
        &quot;server.log.2014-02-12&quot;,
        &quot;server.log.2014-02-13&quot;
    ]
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="read-log-file"><a class="anchor" href="#read-log-file"></a><a class="link" href="#read-log-file">Read Log File</a></h5>
<div class="paragraph">
<p>The <code>read-log-file</code> operation is available on each <code>log-file</code> resource.
This operation has 4 optional parameters.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">encoding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the encoding the file should be read in</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">lines</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the number of lines from the file. A value of -1 indicates all
lines should be read.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">skip</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the number of lines to skip before reading.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">tail</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true to read from the end of the file up or false to read top
down.</p></td>
</tr>
</tbody>
</table>
<div class="listingblock">
<div class="title">CLI command and output</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=logging/log-file=server.log:read-log-file
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        &quot;2014-02-14 14:16:48,781 INFO  [org.jboss.as.server.deployment.scanner] (MSC service thread 1-11) JBAS015012: Started FileSystemDeploymentService for directory /home/jperkins/servers/wildfly-8.0.0.Final/standalone/deployments&quot;,
        &quot;2014-02-14 14:16:48,782 INFO  [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-8) JBAS010400: Bound data source [java:jboss/myDs]&quot;,
        &quot;2014-02-14 14:16:48,782 INFO  [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-15) JBAS010400: Bound data source [java:jboss/datasources/ExampleDS]&quot;,
        &quot;2014-02-14 14:16:48,786 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-9) JBAS015876: Starting deployment of \&quot;simple-servlet.war\&quot; (runtime-name: \&quot;simple-servlet.war\&quot;)&quot;,
        &quot;2014-02-14 14:16:48,978 INFO  [org.jboss.ws.common.management] (MSC service thread 1-10) JBWS022052: Starting JBoss Web Services - Stack CXF Server 4.2.3.Final&quot;,
        &quot;2014-02-14 14:16:49,160 INFO  [org.wildfly.extension.undertow] (MSC service thread 1-16) JBAS017534: Registered web context: /simple-servlet&quot;,
        &quot;2014-02-14 14:16:49,189 INFO  [org.jboss.as.server] (Controller Boot Thread) JBAS018559: Deployed \&quot;simple-servlet.war\&quot; (runtime-name : \&quot;simple-servlet.war\&quot;)&quot;,
        &quot;2014-02-14 14:16:49,224 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015961: Http management interface listening on http://127.0.0.1:9990/management&quot;,
        &quot;2014-02-14 14:16:49,224 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990&quot;,
        &quot;2014-02-14 14:16:49,225 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: WildFly {wildflyVersion}.0.0.Final \&quot;WildFly\&quot; started in 1906ms - Started 258 of 312 services (90 services are lazy, passive or on-demand)&quot;
    ]
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="faq"><a class="anchor" href="#faq"></a><a class="link" href="#faq">7.5.6. FAQ</a></h4>
<div class="sect4">
<h5 id="why-is-there-a-logging.properties-file"><a class="anchor" href="#why-is-there-a-logging.properties-file"></a><a class="link" href="#why-is-there-a-logging.properties-file">Why is there a logging.properties file?</a></h5>
<div class="paragraph">
<p>You may have noticed that there is a <code>logging.properties</code> file in the
configuration directory. This is logging configuration is used when the
server boots up until the logging subsystem kicks in. If the logging
subsystem is not included in your configuration, then this would act as
the logging configuration for the entire server.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <code>logging.properties</code> file is overwritten at boot and with each
change to the logging subsystem. Any changes made to the file are not
persisted. Any changes made to the XML configuration or via management
operations will be persisted to the <code>logging.properties</code> file and used
on the next boot.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="logging-formatters"><a class="anchor" href="#logging-formatters"></a><a class="link" href="#logging-formatters">7.5.7. Logging Formatters</a></h4>
<div class="paragraph">
<p>Formatters are used to format a log message. A formatter can be assigned to a logging handler.</p>
</div>
<div class="paragraph">
<p>The logging subsystem includes 4 types of handlers:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#json-formatter">JSON Formatter</a></p>
</li>
<li>
<p><a href="#pattern-formatter">Pattern Formatter</a></p>
</li>
<li>
<p><a href="#xml-formatter">XML Formatter</a></p>
</li>
<li>
<p><a href="#custom-formatter">Custom Formatter</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="json-formatter"><a class="anchor" href="#json-formatter"></a><a class="link" href="#json-formatter">JSON Formatter</a></h5>
<div class="paragraph">
<p>A formatter used to format log messages in JSON.</p>
</div>
<div class="sect5">
<h6 id="examples"><a class="anchor" href="#examples"></a><a class="link" href="#examples">Examples</a></h6>
<div class="listingblock">
<div class="title">Simple JSON Formatter</div>
<div class="content">
<pre>/subsystem=logging/json-formatter=json:add(pretty-print=true, exception-output-type=formatted)</pre>
</div>
</div>
<div class="listingblock">
<div class="title">Logstash Formatter</div>
<div class="content">
<pre>/subsystem=logging/json-formatter=logstash:add(exception-output-type=formatted, key-overrides=[timestamp="@timestamp"],
meta-data=[@version=1])</pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="pattern-formatter"><a class="anchor" href="#pattern-formatter"></a><a class="link" href="#pattern-formatter">Pattern Formatter</a></h5>
<div class="paragraph">
<p>A formatter used to format log messages in plain text. The following table describes the format characters for the
pattern formatter.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<mark>Highlighted</mark> symbols indicate the calculation of the caller is required which can be expensive to resolve.
</td>
</tr>
</table>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. Pattern Syntax</caption>
<colgroup>
<col style="width: 12.5%;">
<col style="width: 62.5%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Symbol</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Examples</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%c</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The category of the logging event. A precision specifier can be used to alter the dot delimited category</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%c      org.jboss.example.Foo
%c{1}   Foo
%c{2}   example.Foo
%c{.}   ...Foo
%c{1.}  o.j.e.Foo
%c{1~.} o.~.~.Foo</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%C</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The class of the code calling the log method. A precision specifier can be used to alter the dot delimited class name.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%C      org.jboss.example.Foo
%C{1}   Foo
%C{2}   example.Foo
%C{.}   ...Foo
%C{1.}  o.j.e.Foo
%C{1~.} o.~.~.Foo</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><a id="timestamp"></a>%d</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The timestamp the log message. Any valid <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html"><code>SimpleDateFormat</code></a> pattern. The
 default is <code>yyyy-MM-dd HH:mm:ss,SSS</code>.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%d{HH:mm:ss,SSS}
%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%D</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the module the log message came from. A precision specifier can be used to alter the dot delimited module
 name.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%D      org.jboss.example
%D{1}   example
%D{2}   jboss.example
%D{.}   ..example
%D{1.}  o.j.example
%D{1~.} o.~.example</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%e</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The exception stack trace. Accepts an argument to indicate how many levels of suppressed messages to print.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><table class="tableblock frame-none grid-none stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%e</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prints the full stack trace.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%e{0}</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prints the stack trace ignoring any suppressed messages.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%e{1}</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prints the stack trace with a maximum of one suppressed message.</p></td>
</tr>
</tbody>
</table></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%F</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the file the class that logged the message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%h</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The short host name. This will be the first portion of the qualified host name.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%h     localhost</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%H</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The qualified host name. A precision specifier can be used to alter the dot delimited host name.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%H    developer.jboss.org
%H{1} developer</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%i</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The process id.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%k</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The resource bundle key.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%K</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If colored output is supported defines the colors to map to the log message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><table class="tableblock frame-none grid-none stretch">
<colgroup>
<col style="width: 16.6666%;">
<col style="width: 83.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%K{level}</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level determines the color of the output.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%K{red}</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">All messages will be colored red.</p></td>
</tr>
</tbody>
</table></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%l</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The location information. This includes the callers class name, method name, file name and line number.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%l    org.jboss.example.Foo.bar(Foo.java:33)</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%L</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The line number of the caller.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%m</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The formatted message including any stack traces.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%M</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The callers method name.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%n</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A platform independent line separator.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%N</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the process.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%p</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The level of the logged message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%P</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The localized level of the logged message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%r</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The relative number of milliseconds since the given base time from the log message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The simple formatted message. This will not include the stack trace if a cause was logged.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%t</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the callers thread.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><mark>%v</mark></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The version of the module. A precision specifier can be used to alter the dot delimited module version.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%x</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The nested diagnostic context entries. A precision specifier can be used to specify the number of entries to print.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>%x      value1.value2.value3
%x{1}   value3
%x{2}   value2.value3</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%X</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The mapped diagnostic context entry. The entry must be followed by the key for the MDC entry.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>%X{key}</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%z</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows the timezone to be overridden when formatting the <a href="#timestamp">timestamp</a>. This must precede the
 <a href="#timestamp">timestamp</a>.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>%z{GMT}%d{yyyy-MM-dd&#8217;T&#8217;HH:mm:ssSSSXXX}</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%#</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows a system property to be appended to the log message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>%#{jboss.server.name}</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%$</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows a system property to be appended to the log message.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>%${jboss.server.name}</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">%%</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Escapes the <code>%</code> symbol.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>&nbsp;</p>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>You can also modify the format by placing the optional format modifier between the percent sign and the symbol.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 2. Format Modifier Examples</caption>
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 42.8572%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Modifier</th>
<th class="tableblock halign-center valign-top">Left Justify</th>
<th class="tableblock halign-right valign-top">Min Width</th>
<th class="tableblock halign-right valign-top">Max Width</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">[%20c]</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">20</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">&nbsp;</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>[  org.jboss.example]</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">[%-20c]</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">20</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">&nbsp;</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>[org.jboss.example  ]</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">[%.10c]</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&nbsp;</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">&nbsp;</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">10</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>[org.jboss]</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">[%20.30c]</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">20</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">30</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>[  org.jboss.example]</pre>
</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">[%-20.30c]</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">20</p></td>
<td class="tableblock halign-right valign-top"><p class="tableblock">30</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>[org.jboss.example  ]</pre>
</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="sect5">
<h6 id="examples-2"><a class="anchor" href="#examples-2"></a><a class="link" href="#examples-2">Examples</a></h6>
<div class="listingblock">
<div class="title">Simple Pattern Formatter</div>
<div class="content">
<pre>/subsystem=logging/pattern-formatter=DEFAULT:add(pattern="%d{HH:mm:ssSSSXXX} %-5p [%c] (%t) %10.10#{jboss.node.name} %s%e%n")</pre>
</div>
</div>
<div class="listingblock">
<div class="title">Color Pattern Formatter</div>
<div class="content">
<pre>/subsystem=logging/pattern-formatter=DEFAULT:add(color-map="info:cyan,warn:brightyellow,error:brightred,debug:magenta", pattern="%K{level}%d{yyyy-MM-dd'T'HH:mm:ssSSSXXX} %-5p [%c] (%t) %s%e%n")</pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="xml-formatter"><a class="anchor" href="#xml-formatter"></a><a class="link" href="#xml-formatter">XML Formatter</a></h5>
<div class="paragraph">
<p>A formatter used to format log messages in XML.</p>
</div>
<div class="sect5">
<h6 id="examples-3"><a class="anchor" href="#examples-3"></a><a class="link" href="#examples-3">Examples</a></h6>
<div class="listingblock">
<div class="title">Simple XML Formatter</div>
<div class="content">
<pre>/subsystem=logging/xml-formatter=xml:add(pretty-print=true, exception-output-type=detailed-and-formatted)</pre>
</div>
</div>
<div class="listingblock">
<div class="title">Key Overrides XML Formatter</div>
<div class="content">
<pre>/subsystem=logging/xml-formatter=xml:add(pretty-print=true, print-namespace=true, namespace-uri="urn:custom:1.0", key-overrides={message=msg, record=logRecord, timestamp=date}, print-details=true)</pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="custom-formatter"><a class="anchor" href="#custom-formatter"></a><a class="link" href="#custom-formatter">Custom Formatter</a></h5>
<div class="paragraph">
<p>A custom formatter to be used with handlers. Note that most log records are formatted in the printf format. Formatters
may require invocation of the <code>org.jboss.logmanager.ExtLogRecord#getFormattedMessage()</code> for the message to be properly
formatted.</p>
</div>
<div class="sect5">
<h6 id="examples-4"><a class="anchor" href="#examples-4"></a><a class="link" href="#examples-4">Examples</a></h6>
<div class="listingblock">
<div class="content">
<pre>/subsystem=logging/custom-formatter=custom:add(class=org.jboss.example.CustomFormatter, module=org.jboss.example, properties={prettyPrint=true,printDetails=true,bufferSize=1024})</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="handlers"><a class="anchor" href="#handlers"></a><a class="link" href="#handlers">7.5.8. Handlers</a></h4>
<div class="sect4">
<h5 id="overview"><a class="anchor" href="#overview"></a><a class="link" href="#overview">Overview</a></h5>
<div class="paragraph">
<p>Handlers define how log messages are recorded. If a message is said to be
{oracle-javadocs}/java.logging/java/util/logging/Logger.html#isLoggable-java.util.logging.Level-[loggable] by a
<a href="#Logging_Loggers">logger</a> the message is then processed by the log handler.</p>
</div>
<div class="paragraph">
<p>The following are the available handlers for WildFly Full;</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#async-handler">async-handler</a></p>
</li>
<li>
<p><a href="#console-handler">console-handler</a></p>
</li>
<li>
<p><a href="#custom-handler">custom-handler</a></p>
</li>
<li>
<p><a href="#file-handler">file-handler</a></p>
</li>
<li>
<p><a href="#periodic-rotating-file-handler">periodic-rotating-file-handler</a></p>
</li>
<li>
<p><a href="#periodic-size-rotating-file-handler">periodic-size-rotating-file-handler</a></p>
</li>
<li>
<p><a href="#size-rotating-file-handler">size-rotating-file-handler</a></p>
</li>
<li>
<p><a href="#socket-handler">socket-handler</a></p>
</li>
<li>
<p><a href="#syslog-handler">syslog-handler</a></p>
</li>
</ul>
</div>
<div class="sect5">
<h6 id="async-handler"><a class="anchor" href="#async-handler"></a><a class="link" href="#async-handler">async-handler</a></h6>
<div class="paragraph">
<p>An <code>async-handler</code> is a handler that asynchronously writes log messages to it&#8217;s child handlers. This type of
handler is generally used to wrap other handlers that take a substantial time to write messages.</p>
</div>
</div>
<div class="sect5">
<h6 id="console-handler"><a class="anchor" href="#console-handler"></a><a class="link" href="#console-handler">console-handler</a></h6>
<div class="paragraph">
<p>A <code>console-handler</code> is a handler that writes log messages to the console. Generally this writes to <code>stdout</code>,
but can be set to write to <code>stderr</code>.</p>
</div>
</div>
<div class="sect5">
<h6 id="custom-handler"><a class="anchor" href="#custom-handler"></a><a class="link" href="#custom-handler">custom-handler</a></h6>
<div class="paragraph">
<p>A <code>custom-handler</code> allows you to define any <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/Handler.html">handler</a> as a handler that
can be assigned to a logger or a <a href="#async-handler"><code>async-handler</code></a>.</p>
</div>
</div>
<div class="sect5">
<h6 id="file-handler"><a class="anchor" href="#file-handler"></a><a class="link" href="#file-handler">file-handler</a></h6>
<div class="paragraph">
<p>A <code>file-handler</code> is a handler that writes log messages to the specified file.</p>
</div>
</div>
<div class="sect5">
<h6 id="periodic-rotating-file-handler"><a class="anchor" href="#periodic-rotating-file-handler"></a><a class="link" href="#periodic-rotating-file-handler">periodic-rotating-file-handler</a></h6>
<div class="paragraph">
<p>A <code>periodic-rotating-file-handler</code> is a handler that writes log messages to the specified file. The file rotates on
the date pattern specified in the <code>suffix</code> attribute. The suffix must be a valid pattern recognized by the
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html"><code>java.text.SimpleDateFormat</code></a> and must not rotate on seconds or
milliseconds.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The rotate happens before the next message is written by the handler.
</td>
</tr>
</table>
</div>
</div>
<div class="sect5">
<h6 id="periodic-size-rotating-file-handler"><a class="anchor" href="#periodic-size-rotating-file-handler"></a><a class="link" href="#periodic-size-rotating-file-handler">periodic-size-rotating-file-handler</a></h6>
<div class="paragraph">
<p>A <code>periodic-size-rotating-file-handler</code> is a handler that writes log messages to the specified file. The file rotates on
the date pattern specified in the <code>suffix</code> attribute or the <code>rotate-size</code> attribute. The suffix must be a valid
pattern recognized by the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html"><code>java.text.SimpleDateFormat</code></a> and must
not rotate on seconds or milliseconds.</p>
</div>
<div class="paragraph">
<p>The <code>max-backup-index</code> works differently on this handler than the
<a href="#size-rotating-file-handler"><code>size-rotating-file-handler</code></a>. The date suffix of the file to be rotated must be the
same as the current expected suffix. For example with a suffix pattern of <code>yyyy-MM</code> and a <code>rotate-size</code> of <code>10m</code> the
file will be rotated with the current month each time the 10Mb size is reached.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The rotate happens before the next message is written by the handler.
</td>
</tr>
</table>
</div>
</div>
<div class="sect5">
<h6 id="size-rotating-file-handler"><a class="anchor" href="#size-rotating-file-handler"></a><a class="link" href="#size-rotating-file-handler">size-rotating-file-handler</a></h6>
<div class="paragraph">
<p>A <code>size-rotating-file-handler</code> is a handler that writes log messages to the specified file. The file rotates when
the file size is greater than the <code>rotate-size</code> attribute. The rotated file will be kept and the index appended
to the name moving previously rotated file indexes up by 1 until the <code>max-backup-index</code> is reached. Once the
<code>max-backup-index</code> is reached, the indexed files will be overwritten.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The rotate happens before the next message is written by the handler.
</td>
</tr>
</table>
</div>
</div>
<div class="sect5">
<h6 id="socket-handler"><a class="anchor" href="#socket-handler"></a><a class="link" href="#socket-handler">socket-handler</a></h6>
<div class="paragraph">
<p>A <code>socket-handler</code> is a handler which sends messages over a socket. This can be a TCP or UDP socket and must be
defined in a <a href="#socket-binding-groups">socket binding group</a> under the <code>local-destination-outbound-socket-binding</code> or
<code>remote-destination-outbound-socket-binding</code> resource.</p>
</div>
<div class="paragraph">
<p>During the boot logging messages will be queued until the socket binding is configured and the logging subsystem is
added. This is important to note because setting the level of the handler to <code>DEBUG</code> or <code>TRACE</code> could result in
large memory consumption during boot.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>A server booted in <code>--admin-only</code> mode will discard messages rather than send them over a socket.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">CLI Example</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code># Add the socket binding
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)
# Add a json-formatter
/subsystem=logging/json-formatter=json:add
# Add the socket handler
/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server)
# Add the handler to the root logger
/subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Add a UDP Example</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=UDP)</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Add SSL Example</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code># Add the socket binding
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)

# Add the Elytron key store
/subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.jks, type=JKS, credential-reference={clear-text=mypassword})
# Add the Elytron trust manager
/subsystem=elytron/trust-manager=log-server-tm:add(key-store=log-server-ks)
# Add the client SSL context
/subsystem=elytron/client-ssl-context=log-server-context:add(trust-manager=log-server-tm, protocols=[&quot;TLSv1.2&quot;])

# Add a json-formatter
/subsystem=logging/json-formatter=json:add
# Add the socket handler
/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=SSL_TCP, ssl-context=log-server-context)
# Add the handler to the root logger
/subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Wrapping a <code>socket-handler</code> in a <a href="#async-handler"><code>async-handler</code></a> may improve performance.
</td>
</tr>
</table>
</div>
</div>
<div class="sect5">
<h6 id="syslog-handler"><a class="anchor" href="#syslog-handler"></a><a class="link" href="#syslog-handler">syslog-handler</a></h6>
<div class="paragraph">
<p>A <code>syslog-handler</code> is a handler that writes to a syslog server via UDP. The handler support
<a href="http://www.ietf.org/rfc/rfc3164.txt">RFC3164</a> or <a href="http://www.ietf.org/rfc/rfc5424.txt">RFC5424</a> formats.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The syslog-handler is missing some configuration properties that may be
useful in some scenarios like setting a formatter. Use the
<code>org.jboss.logmanager.handlers.SyslogHandler</code> in module
<code>org.jboss.logmanager</code> as a
<a href="#custom-handler">custom-handler</a> to exploit
these benefits. Additional attributes will be added at some point so
this will no longer be necessary.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Logging_How_To"><a class="anchor" href="#Logging_How_To"></a><a class="link" href="#Logging_How_To">7.5.9. How To</a></h4>
<div class="sect4">
<h5 id="how-do-i-add-a-log-category"><a class="anchor" href="#how-do-i-add-a-log-category"></a><a class="link" href="#how-do-i-add-a-log-category">How do I add a log category?</a></h5>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/logger=com.your.category:add</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="how-do-i-change-a-log-level"><a class="anchor" href="#how-do-i-change-a-log-level"></a><a class="link" href="#how-do-i-change-a-log-level">How do I change a log level?</a></h5>
<div class="paragraph">
<p>To change a handlers log level:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=DEBUG)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Changing the level on a log category is the same:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/logger=com.your.category:write-attribute(name=level,value=ALL)</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="how-do-i-log-my-applications-messages-to-their-own-file"><a class="anchor" href="#how-do-i-log-my-applications-messages-to-their-own-file"></a><a class="link" href="#how-do-i-log-my-applications-messages-to-their-own-file">How do I log my applications messages to their own file?</a></h5>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create a file handler. There are 3 different types of file handlers
to choose from; <code>file-handler</code>, <code>periodic-rotating-file-handler</code> and
<code>size-rotating-file-handler</code>. In this example we&#8217;ll just use a simple
<code>file-handler</code>.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/file-handler=fh:add(level=INFO, file={&quot;relative-to&quot;=&gt;&quot;jboss.server.log.dir&quot;, &quot;path&quot;=&gt;&quot;fh.log&quot;}, append=false, autoflush=true)</code></pre>
</div>
</div>
</li>
<li>
<p>Now create the log category.</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=logging/logger=org.your.company:add(use-parent-handlers=false,handlers=[&quot;fh&quot;])</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
<div class="sect4">
<h5 id="how-do-i-log4j2"><a class="anchor" href="#how-do-i-log4j2"></a><a class="link" href="#how-do-i-log4j2">How do I use my own log4j2 implementation?</a></h5>
<div class="paragraph">
<p>If you want to use your own log4j2 implementation, such as log4j-core, then you need to do the following two steps.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Disable the adding of the logging dependencies to all your deployments with the
<a href="#add-logging-api-dependencies">add-logging-api-dependencies</a> attribute <strong>OR</strong> exclude the <code>org.apache.logging.log4j.api</code>
in a <a href="Developer_Guide.html#jboss-deployment-structure-file">jboss-deployment-structure.xml</a>.</p>
</li>
<li>
<p>Then you would need to include the log4j-api and a log4j2 implementation library in your deployment.</p>
</li>
</ol>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This only works for logging in your deployment. Server logs will continue to use the logging subsystem
           configuration.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Logging_Loggers"><a class="anchor" href="#Logging_Loggers"></a><a class="link" href="#Logging_Loggers">7.5.10. Loggers</a></h4>
<div class="paragraph">
<p>WIP</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This is still a work in progress. Please feel free to edit any mistakes
you find <span class="icon yellow"><i class="fa fa-smile-o"></i></span>
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="overview-2"><a class="anchor" href="#overview-2"></a><a class="link" href="#overview-2">Overview</a></h5>
<div class="paragraph">
<p>Loggers are used to log messages. A logger is defined by a category
generally consisting of a package name or a class name.</p>
</div>
<div class="paragraph">
<p>A logger is the first step to determining if a messages should be logged
or not. If a logger is defined with a level, the level of the message
must be greater than the level defined on the logger. The filter is then
checked next and the rules of the filter will determine whether or not
the messages is said to be loggable.</p>
</div>
<div class="sect5">
<h6 id="logger-resource"><a class="anchor" href="#logger-resource"></a><a class="link" href="#logger-resource">Logger Resource</a></h6>
<div class="paragraph">
<p>A logger resource uses the path <code>subsystem=logging/logger=$category</code>
where <code>$category</code> is the of the logger. For example to a logger named
org.wildfly.example would have a resource path of
<code>subsystem=logging/logger=org.wildfly.example</code>.</p>
</div>
<div class="paragraph">
<p>A logger as 4 writeable attributes;</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#filter-spec">filter-spec</a></p>
</li>
<li>
<p><a href="#level">#handlers</a></p>
</li>
<li>
<p><a href="#level">#level</a></p>
</li>
<li>
<p><a href="#Loggers-use-parent-handlers">use-parent-handlers</a></p>
</li>
</ul>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
You may notice that the <code>category</code> and <code>filter</code> attributes are missing.
While <code>filter</code> is writable it may be deprecated and removed in the
future. Both attributes are still on the resource for legacy reasons.
</td>
</tr>
</table>
</div>
<div class="sect6">
<h7 id="filter-spec"><a class="anchor" href="#filter-spec"></a><a class="link" href="#filter-spec">filter-spec</a></h7>
<div class="paragraph">
<p>The <code>filter-spec</code> attribute is an expression based string to define
filters for the logger.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Filters on loggers are not inherited.
</td>
</tr>
</table>
</div>
</div>
<div class="sect6">
<h7 id="handlers-2"><a class="anchor" href="#handlers-2"></a><a class="link" href="#handlers-2">handlers</a></h7>
<div class="paragraph">
<p>The <code>handlers</code> attribute is a list of handler names that should be
attached to the logger. If the
<a href="#use-parent-handlers">use-parent-handlers</a>
attribute is set to <code>true</code> and the log messages is determined to be
loggable, parent loggers will continue to be processed.</p>
</div>
</div>
<div class="sect6">
<h7 id="level"><a class="anchor" href="#level"></a><a class="link" href="#level">level</a></h7>
<div class="paragraph">
<p>The <code>level</code> attribute allows the minimum level to allow messages to be
logged at for the logger.</p>
</div>
</div>
<div class="sect6">
<h7 id="use-parent-handlers"><a class="anchor" href="#use-parent-handlers"></a><a class="link" href="#use-parent-handlers">use-parent-handlers</a></h7>
<div class="paragraph">
<p>The <code>use-parent-handlers</code> attribute is a boolean attribute to determine
whether or not parent loggers should also process the log message.</p>
</div>
</div>
</div>
<div class="sect5">
<h6 id="root-logger-resource"><a class="anchor" href="#root-logger-resource"></a><a class="link" href="#root-logger-resource">Root Logger Resource</a></h6>
<div class="paragraph">
<p>The <code>root-logger</code> is similar to a
<a href="#logger-resource">#Logger Resource</a> only it has no
category and it&#8217;s name is must be <code>ROOT</code>.</p>
</div>
</div>
<div class="sect5">
<h6 id="logger-hierarchy"><a class="anchor" href="#logger-hierarchy"></a><a class="link" href="#logger-hierarchy">Logger Hierarchy</a></h6>
<div class="paragraph">
<p>A logger hierarchy is defined by it&#8217;s category. The category is a <code>.</code>
(dot) delimited string generally consisting of the package name or a
class name. For example the logger <code>org.wildfly</code> is the parent logger of
<code>org.wildfly.example</code>.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="logging-filters"><a class="anchor" href="#logging-filters"></a><a class="link" href="#logging-filters">7.5.11. Logging Filters</a></h4>
<div class="paragraph">
<p>Filters are used to add fine grained control over a log message. A filter can be assigned to a logger or log handler.
See the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/Filter.html">Filter</a> documentation for details on filters.</p>
</div>
<div class="sect4">
<h5 id="filter"><a class="anchor" href="#filter"></a><a class="link" href="#filter">Filter</a></h5>
<div class="paragraph">
<p>The filter resource allows a custom filter to be used. The custom filter must reside in a module and implement the
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/Filter.html">Filter</a> interface.</p>
</div>
<div class="paragraph">
<p>It&#8217;s generally suggested to add filters to a handler. By default loggers do no inherit filters. This means if a filter
is placed on a logger named <code>org.jboss.as.logging</code> is only checked if the logger name is equal to <code>org.jboss.as.logging</code>.</p>
</div>
<div class="sect5">
<h6 id="examples-5"><a class="anchor" href="#examples-5"></a><a class="link" href="#examples-5">Examples</a></h6>
<div class="listingblock">
<div class="title">Adding a filter</div>
<div class="content">
<pre>/subsystem=logging/filter=myFilter:add(class=org.jboss.example.MyFilter, module=org.jboss.example, properties={matches="true"}, constructor-properties={pattern="*.WFLYLOG.*"))</pre>
</div>
</div>
<div class="listingblock">
<div class="title">Nesting a filter</div>
<div class="content">
<pre>/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value=not(myFilter))</pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="filter-expressions"><a class="anchor" href="#filter-expressions"></a><a class="link" href="#filter-expressions">Filter Expressions</a></h5>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Filter Type</th>
<th class="tableblock halign-left valign-top">Expression</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Parameter(s)</th>
<th class="tableblock halign-left valign-top">Examples</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">accept</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">accept</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Accepts all log messages.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">accept</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">deny</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">deny</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Denies all log messages.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">deny</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">not</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">not(filterExpression)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Accepts a filter as an argument and inverts
the returned value.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expression takes a single filter for it&#8217;s
argument.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">not(match("JBAS"))</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">all</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">all(filterExpressions)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter consisting of several filters in
a chain. If any filter find the log message to be unloggable, the
message will not be logged and subsequent filters will not be checked.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expression takes a comma delimited list of filters for it&#8217;s
argument.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">all(match("JBAS"), match("WELD"))</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">any</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any(filterExpressions)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter consisting of several filters in
a chain. If any filter fins the log message to be loggable, the message
will be logged and the subsequent filters will not be checked.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The
expression takes a comma delimited list of filters for it&#8217;s argument.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any(match("JBAS"), match("WELD"))</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">levelChange</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">levelChange(level)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter which modifies the log record
with a new level.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expression takes a single string based level for
it&#8217;s argument.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">levelChange(WARN)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">levels</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">levels(levels)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter which includes log messages with a
level that is listed in the list of levels.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expression takes a
comma delimited list of string based levels for it&#8217;s argument.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">levels(DEBUG, INFO, WARN, ERROR)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">levelRange</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">levelRange([minLevel,maxLevel])</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter which logs
records that are within the level range.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The filter expression uses a
"[" to indicate a minimum inclusive level and a "]" to indicate a
maximum inclusive level. Otherwise use "(" or ")" respectively indicate
exclusive. The first argument for the expression is the minimum level
allowed, the second argument is the maximum level allowed.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">minimum
level must be less than ERROR and the maximum level must be greater than
DEBUGlevelRange(ERROR, DEBUG) minimum level must be less than or equal
to ERROR and the maximum level must be greater than
DEBUGlevelRange[ERROR, DEBUG) minimum level must be less than or equal
to ERROR and the maximum level must be greater or equal to
INFOlevelRange[ERROR, INFO]</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">match</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">match("pattern")</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A regular-expression based filter. The raw
unformatted message is used against the pattern.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expression takes a
regular expression for it&#8217;s argument. match("JBAS\d+")</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">substitute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">substitute("pattern", "replacement value")</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter which
replaces the first match to the pattern with the replacement value.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The
first argument for the expression is the pattern the second argument is
the replacement text.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">substitute("JBAS", "EAP")</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">substituteAll</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">substituteAll("pattern", "replacement value")</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A filter
which replaces all matches of the pattern with the replacement value.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The first argument for the expression is the pattern the second
argument is the replacement text.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">substituteAll("JBAS", "EAP")</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>filterName</em></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">myCustomFilter</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A custom filter which is defined on a <code>filter</code> resource.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">myCustomFilter<br>
any(myFilter1, myFilter2, myFilter3)</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="EJB3"><a class="anchor" href="#EJB3"></a><a class="link" href="#EJB3">7.6. EJB3 subsystem configuration guide</a></h3>
<div class="paragraph">
<p>This page lists the options that are available for configuring the EJB
subsystem.</p>
</div>
<div class="paragraph">
<p>A complete example of the config is shown below, with a full explanation
of each</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:ejb3:10.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  <span class="tag">&lt;session-bean&gt;</span>
    <span class="tag">&lt;stateless&gt;</span>
      <span class="tag">&lt;bean-instance-pool-ref</span> <span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">slsb-strict-max-pool</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/stateless&gt;</span>
    <span class="tag">&lt;stateful</span> <span class="attribute-name">default-session-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">600000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-access-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">cache-ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">distributable</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">passivation-disabled-cache-ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;singleton</span> <span class="attribute-name">default-access-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/session-bean&gt;</span>
  <span class="tag">&lt;mdb&gt;</span>
    <span class="tag">&lt;resource-adapter-ref</span> <span class="attribute-name">resource-adapter-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hornetq-ra</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;bean-instance-pool-ref</span> <span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mdb-strict-max-pool</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/mdb&gt;</span>
  <span class="tag">&lt;entity-bean&gt;</span>
    <span class="tag">&lt;bean-instance-pool-ref</span> <span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">entity-strict-max-pool</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/entity-bean&gt;</span>
    <span class="tag">&lt;pools&gt;</span>
    <span class="tag">&lt;bean-instance-pools&gt;</span>
      <span class="tag">&lt;strict-max-pool</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">slsb-strict-max-pool</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-pool-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">20</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout-unit</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MINUTES</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;strict-max-pool</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mdb-strict-max-pool</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-pool-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">20</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout-unit</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MINUTES</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;strict-max-pool</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">entity-strict-max-pool</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-pool-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">instance-acquisition-timeout-unit</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MINUTES</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/bean-instance-pools&gt;</span>
  <span class="tag">&lt;/pools&gt;</span>
  <span class="tag">&lt;caches&gt;</span>
    <span class="tag">&lt;simple-cache</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">simple</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;distributable-cache</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">distributable</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">bean-management</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/caches&gt;</span>
  <span class="tag">&lt;async</span> <span class="attribute-name">thread-pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;timer-service</span> <span class="attribute-name">thread-pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-data-store</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-file-store</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;data-stores&gt;</span>
      <span class="tag">&lt;file-data-store</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-file-store</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">timer-service-data</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.data.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/data-stores&gt;</span>
  <span class="tag">&lt;/timer-service&gt;</span>
  <span class="tag">&lt;remote</span> <span class="attribute-name">connectors</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">remoting-connector</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">thread-pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;profiles&gt;</span>
        <span class="tag">&lt;profile</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">profile</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">exclude-local-receiver</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">local-receiver-pass-by-value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
          <span class="tag">&lt;remoting-ejb-receiver</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">receiver</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">outbound-connection-ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">remote-ejb-connection</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
          <span class="tag">&lt;remote-http-connection</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">connection</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">uri</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8180/wildfly-services</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
          <span class="tag">&lt;static-ejb-discovery&gt;</span>
            <span class="tag">&lt;module</span> <span class="attribute-name">uri</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8180/wildfly-services</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">foo</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">app-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bar</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">distinct-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">baz</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
          <span class="tag">&lt;/static-ejb-discovery&gt;</span>
        <span class="tag">&lt;/profile&gt;</span>
    <span class="tag">&lt;/profiles&gt;</span>
  <span class="tag">&lt;/remote&gt;</span>
  <span class="tag">&lt;thread-pools&gt;</span>
    <span class="tag">&lt;thread-pool</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;max-threads</span> <span class="attribute-name">count</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;core-threads</span> <span class="attribute-name">count</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;keepalive-time</span> <span class="attribute-name">time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">60</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">unit</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">seconds</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/thread-pool&gt;</span>
  <span class="tag">&lt;/thread-pools&gt;</span>
  <span class="tag">&lt;iiop</span> <span class="attribute-name">enable-by-default</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">use-qualified-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;in-vm-remote-interface-invocation</span> <span class="attribute-name">pass-by-value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span> <span class="comment">&lt;!-- Warning see notes below about possible issues --&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="session-bean"><a class="anchor" href="#session-bean"></a><a class="link" href="#session-bean">7.6.1. &lt;session-bean&gt;</a></h4>
<div class="sect4">
<h5 id="stateless"><a class="anchor" href="#stateless"></a><a class="link" href="#stateless">&lt;stateless&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure the instance pool that is used by
default for stateless session beans. If it is not present stateless
session beans are not pooled, but are instead created on demand for
every invocation. The instance pool can be overridden on a per
deployment or per bean level using <code>jboss-ejb3.xml</code> or the
<code>org.jboss.ejb3.annotation.Pool</code> annotation. The instance pools
themselves are configured in the <code>&lt;pools&gt;</code> element.</p>
</div>
</div>
<div class="sect4">
<h5 id="stateful"><a class="anchor" href="#stateful"></a><a class="link" href="#stateful">&lt;stateful&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure Stateful Session Beans.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>default-session-timeout</code> This optional attribute specifies the default
amount of time in milliseconds a stateful session bean can remain idle
before it is eligible for removal by the container.
It can be overridden via <code>ejb-jar.xml</code> deployment descriptor or via
<code>jakarta.ejb.StatefulTimeout</code> annotation.</p>
</li>
<li>
<p><code>default-access-timeout</code> This attribute specifies the default time
concurrent invocations on the same bean instance will wait to acquire
the instance lock. It can be overridden via the deployment descriptor or
via the <code>jakarta.ejb.AccessTimeout</code> annotation.</p>
</li>
<li>
<p><code>cache-ref</code> This attribute is used to set the default cache for
beans which require a passivating cache. It can be overridden by <code>jboss-ejb3.xml</code>, or via
the <code>org.jboss.ejb3.annotation.Cache</code> annotation.</p>
</li>
<li>
<p><code>non-passivating-cache-ref</code> This attribute is used to set the default cache
for beans which require a non-passivating cache.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="singleton"><a class="anchor" href="#singleton"></a><a class="link" href="#singleton">&lt;singleton&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure Singleton Session Beans.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>default-access-timeout</code> This attribute specifies the default time
concurrent invocations will wait to acquire the instance lock. It can be
overridden via the deployment descriptor or via the
<code>jakarta.ejb.AccessTimeout</code> annotation.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="mdb"><a class="anchor" href="#mdb"></a><a class="link" href="#mdb">7.6.2. &lt;mdb&gt;</a></h4>
<div class="sect4">
<h5 id="resource-adaptor-ref"><a class="anchor" href="#resource-adaptor-ref"></a><a class="link" href="#resource-adaptor-ref">&lt;resource-adaptor-ref&gt;</a></h5>
<div class="paragraph">
<p>This element sets the default resource adaptor for Message Driven Beans.</p>
</div>
</div>
<div class="sect4">
<h5 id="bean-instance-pool-ref"><a class="anchor" href="#bean-instance-pool-ref"></a><a class="link" href="#bean-instance-pool-ref">&lt;bean-instance-pool-ref&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure the instance pool that is used by
default for Message Driven Beans. If it is not present they are not
pooled, but are instead created on demand for every invocation. The
instance pool can be overridden on a per deployment or per bean level
using <code>jboss-ejb3.xml</code> or the <code>org.jboss.ejb3.annotation.Pool</code>
annotation. The instance pools themselves are configured in the
<code>&lt;pools&gt;</code> element.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="entity-bean"><a class="anchor" href="#entity-bean"></a><a class="link" href="#entity-bean">7.6.3. &lt;entity-bean&gt;</a></h4>
<div class="paragraph">
<p>This element is used to configure the behavior for EJB2 EntityBeans.</p>
</div>
<div class="sect4">
<h5 id="bean-instance-pool-ref-1"><a class="anchor" href="#bean-instance-pool-ref-1"></a><a class="link" href="#bean-instance-pool-ref-1">&lt;bean-instance-pool-ref&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure the instance pool that is used by
default for Entity Beans. If it is not present they are not pooled, but
are instead created on demand for every invocation. The instance pool
can be overridden on a per deployment or per bean level using
<code>jboss-ejb3.xml</code> or the <code>org.jboss.ejb3.annotation.Pool</code> annotation. The
instance pools themselves are configured in the <code>&lt;pools&gt;</code> element.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="pools"><a class="anchor" href="#pools"></a><a class="link" href="#pools">7.6.4. &lt;pools&gt;</a></h4>
<div class="sect4">
<h5 id="bean-instance-pools"><a class="anchor" href="#bean-instance-pools"></a><a class="link" href="#bean-instance-pools">&lt;bean-instance-pools&gt;</a></h5>
<div class="paragraph">
<p>This element is used to configure pools used by stateless session, message driven beans and entity beans.</p>
</div>
<div class="sect5">
<h6 id="strict-max-pool"><a class="anchor" href="#strict-max-pool"></a><a class="link" href="#strict-max-pool">&lt;strict-max-pool&gt;</a></h6>
<div class="paragraph">
<p>Each pool is configured using <code>strict-max-pool</code> element.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> Name of the pool.</p>
</li>
<li>
<p><code>max-pool-size</code> Configured maximum number of bean instances that the pool can hold at a given point in time.</p>
</li>
<li>
<p><code>instance-acquisition-timeout</code> The maximum amount of time to wait for a bean instance to be available from the pool.</p>
</li>
<li>
<p><code>instance-acquisition-timeout-unit</code> The instance acquisition timeout unit</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="caches"><a class="anchor" href="#caches"></a><a class="link" href="#caches">7.6.5. &lt;caches&gt;</a></h4>
<div class="paragraph">
<p>This element is used to define named cache factories to support the persistence of SFSB session states.
Cache factories may be passivating (an in-memory cache with the ability to passivate to persistant store
the session states of beans not recently used and then activate them when needed) or non-passivating
(an in-memory cache only). Default values for passivating and non-passivating caches are specified
in the &lt;stateful&gt; element mentioned above. A SFSB may override the named cache used to store its session states
via the @Cache annotation (in its class definition) or via a corresponding deployment descriptor.</p>
</div>
<div class="sect4">
<h5 id="simple-cache"><a class="anchor" href="#simple-cache"></a><a class="link" href="#simple-cache">&lt;simple-cache&gt;</a></h5>
<div class="paragraph">
<p>This element defines a non-passivating (in-memory only) cache factory for storing session states of a SFSB.</p>
</div>
</div>
<div class="sect4">
<h5 id="distributable-cache"><a class="anchor" href="#distributable-cache"></a><a class="link" href="#distributable-cache">&lt;distributable-cache&gt;</a></h5>
<div class="paragraph">
<p>This element defines a passivating cache factory (in-memory plus passivation to persistent store) for storing
session states of a SFSB. A passivating cache factory relies on a bean-management provider to configure
the passivation mechanism and the persistent store that it uses.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>bean-management</code> This attribute specifies the bean-management provider to be used to
support passivation of cache entries. The bean-management provider is defined and configured
in the distributable-ejb subsystem (see the <a href="High_Availability_Guide.html">High Availability Guide</a>).
If the attribute is non-defined, the default bean management provider
defined in the distributable-ejb subsystem is used.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="async"><a class="anchor" href="#async"></a><a class="link" href="#async">7.6.6. &lt;async&gt;</a></h4>
<div class="paragraph">
<p>This element enables async EJB invocations. It is also used to specify
the thread pool that these invocations will use.</p>
</div>
</div>
<div class="sect3">
<h4 id="timer-service"><a class="anchor" href="#timer-service"></a><a class="link" href="#timer-service">7.6.7. &lt;timer-service&gt;</a></h4>
<div class="paragraph">
<p>This element enables the EJB timer service. It is also used to specify
the thread pool that these invocations will use.</p>
</div>
<div class="sect4">
<h5 id="data-store"><a class="anchor" href="#data-store"></a><a class="link" href="#data-store">&lt;data-store&gt;</a></h5>
<div class="paragraph">
<p>This is used to configure the directory that persistent timer
information is saved to.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="remote"><a class="anchor" href="#remote"></a><a class="link" href="#remote">7.6.8. &lt;remote&gt;</a></h4>
<div class="paragraph">
<p>This element is used to enable remote EJB invocations. In other words, it allows a remote EJB client
application to make invocations on Jakarta Enterprise beans deployed on the server.</p>
</div>
<div class="paragraph">
<p>It specifies the following attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>connectors</code> specifies a space-separated list of remoting connectors to use (as defined in the remoting
subsystem configuration) for accepting invocations.</p>
</li>
<li>
<p><code>thread-pool</code> specifies a thread pool to use for processing incoming remote invocations</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="profile"><a class="anchor" href="#profile"></a><a class="link" href="#profile">&lt;profile&gt;</a></h5>
<div class="paragraph">
<p>A remote profile specifies a configuration of remote invocations that can
be referenced by many deployments. EJBs that are meant to be invoked can
be discovered in either a static or a dynamic way.</p>
</div>
<div class="paragraph">
<p>Static discovery decides which remote node to connect to based on the information
provided by the administrator.</p>
</div>
<div class="paragraph">
<p>Dynamic discovery is responsible for monitoring the available EJBs on all the
nodes to which connections are configured and decides which remote node to
connect to based on the gathered data.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> the name of the profile</p>
</li>
<li>
<p><code>exclude-local-receiver</code> If set, no local receiver is used in this profile</p>
</li>
<li>
<p><code>local-receiver-pass-by-value</code> If set, local receiver will pass ejb beans by value</p>
</li>
</ul>
</div>
<div class="sect5">
<h6 id="static-ejb-discovery"><a class="anchor" href="#static-ejb-discovery"></a><a class="link" href="#static-ejb-discovery">&lt;static-ejb-discovery&gt;</a></h6>
<div class="paragraph">
<p>Static ejb discovery allows the administrator to explicitly specify on which remote nodes
given EJBs are located. The <code>module</code> tag is used to define it:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>module-name</code> the name of EJB module</p>
</li>
<li>
<p><code>app-name</code> the name of EJB app</p>
</li>
<li>
<p><code>distinct-name</code> the distinct name EJB</p>
</li>
<li>
<p><code>uri</code> the address on which given EJB is located</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6 id="remoting-ejb-receiver"><a class="anchor" href="#remoting-ejb-receiver"></a><a class="link" href="#remoting-ejb-receiver">&lt;remoting-ejb-receiver&gt;</a></h6>
<div class="paragraph">
<p>The <code>remoting-ejb-receiver</code> tag is used to define dynamic discovery based on
the remoting protocol:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> name of the remote connection</p>
</li>
<li>
<p><code>outbound-connection-ref</code> reference to outbound connection defined in
the remoting subsystem</p>
</li>
<li>
<p><code>connection-timeout</code> the timeout of the connection</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6 id="remote-http-connection"><a class="anchor" href="#remote-http-connection"></a><a class="link" href="#remote-http-connection">&lt;remote-http-connection&gt;</a></h6>
<div class="paragraph">
<p>The <code>remote-http-connection</code> tag is used to define dynamic discovery based on
HTTP protocol:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> name of the HTTP connection</p>
</li>
<li>
<p><code>uri</code> URI of the connection</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="thread-pools"><a class="anchor" href="#thread-pools"></a><a class="link" href="#thread-pools">7.6.9. &lt;thread-pools&gt;</a></h4>
<div class="paragraph">
<p>This is used to configure the thread pools used by async, timer and
remote invocations.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>max-threads</code> specifies the maximum number of threads in the thread pool.
It is a required attribute and defaults to <code>10</code>.</p>
</li>
<li>
<p><code>core-threads</code> specifies the number of core threads in the thread pool.
It is an optional attribute and defaults to <code>max-threads</code> value.</p>
</li>
<li>
<p><code>keepalive-time</code> specifies the amount of time that non-core threads can
stay idle before they become eligible for removal. It is an optional
attribute and defaults to <code>60</code> seconds.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="iiop"><a class="anchor" href="#iiop"></a><a class="link" href="#iiop">7.6.10. &lt;iiop&gt;</a></h4>
<div class="paragraph">
<p>This is used to enable IIOP (i.e. CORBA) invocation of EJB&#8217;s. If this
element is present then the JacORB subsystem must also be installed. It
supports the following two attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>enable-by-default</code> If this is true then all EJB&#8217;s with EJB2.x home
interfaces are exposed via IIOP, otherwise they must be explicitly
enabled via <code>jboss-ejb3.xml</code>.</p>
</li>
<li>
<p><code>use-qualified-name</code> If this is true then EJB&#8217;s are bound to the corba
naming context with a binding name that contains the application and
modules name of the deployment (e.g. myear/myejbjar/MyBean), if this is
false the default binding name is simply the bean name.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="in-vm-remote-interface-invocation"><a class="anchor" href="#in-vm-remote-interface-invocation"></a><a class="link" href="#in-vm-remote-interface-invocation">7.6.11. &lt;in-vm-remote-interface-invocation&gt;</a></h4>
<div class="paragraph">
<p>By default remote interface invocations use pass by value, as required
by the EJB spec. This element can use used to enable pass by reference,
which can give you a performance boost. Note WildFly will do a shallow
check to see if the caller and the EJB have access to the same class
definitions, which means if you are passing something such as a
List&lt;MyObject&gt;, WildFly only checks the List to see if it is the same
class definition on the call &amp; EJB side. If the top level class
definition is the same, JBoss will make the call using pass by
reference, which means that if MyObject or any objects beneath it are
loaded from different classloaders, you would get a ClassCastException.
If the top level class definitions are loaded from different
classloaders, JBoss will use pass by value. JBoss cannot do a deep check
of all of the classes to ensure no ClassCastExceptions will occur
because doing a deep check would eliminate any performance boost you
would have received by using call by reference. It is recommended that
you configure pass by reference only on callers that you are sure will
use the same class definitions and not globally. This can be done via a
configuration in the jboss-ejb-client.xml as shown below.</p>
</div>
<div class="paragraph">
<p>To configure a caller/client use pass by reference, you configure your
top level deployment with a META-INF/jboss-ejb-client.xml containing:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;jboss-ejb-client</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:ejb-client:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;client-context&gt;</span>
        <span class="tag">&lt;ejb-receivers</span> <span class="attribute-name">local-receiver-pass-by-value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/client-context&gt;</span>
<span class="tag">&lt;/jboss-ejb-client&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="server-interceptors"><a class="anchor" href="#server-interceptors"></a><a class="link" href="#server-interceptors">7.6.12. &lt;server-interceptors&gt;</a></h4>
<div class="paragraph">
<p>This element configures a number of server-side interceptors which can be
configured without changing the deployments.</p>
</div>
<div class="paragraph">
<p>Each interceptor is configured in <em>&lt;interceptor&gt;</em> tag which contains the
following fields:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>module</code> - the module in which the interceptor is defined</p>
</li>
<li>
<p><code>class</code> - the class which implements the interceptor</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In order to use server interceptors you have to create a module that implements
them and place it into <em>${WILDFLY_HOME}/modules</em> directory.</p>
</div>
<div class="paragraph">
<p>Interceptor implementations are POJO classes which use
<em>jakarta.interceptor.AroundInvoke</em> and <em>jakarta.interceptor.AroundTimeout</em> to
mark interceptor methods.</p>
</div>
<div class="paragraph">
<p>Sample configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;server-interceptors&gt;</span>
        <span class="tag">&lt;interceptor</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo:FooInterceptor:1.0</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.FooInterceptor</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/server-interceptors&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Sample interceptor implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">org.foo</span>;

<span class="keyword">import</span> <span class="include">jakarta.annotation.PostConstruct</span>;
<span class="keyword">import</span> <span class="include">jakarta.interceptor.AroundInvoke</span>;
<span class="keyword">import</span> <span class="include">jakarta.interceptor.InvocationContext</span>;

<span class="directive">public</span> <span class="type">class</span> <span class="class">FooInterceptor</span> {

    <span class="annotation">@AroundInvoke</span>
    <span class="directive">public</span> <span class="predefined-type">Object</span> bar(<span class="directive">final</span> InvocationContext invocationContext) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="keyword">return</span> invocationContext.proceed();
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="client-interceptors"><a class="anchor" href="#client-interceptors"></a><a class="link" href="#client-interceptors">7.6.13. &lt;client-interceptors&gt;</a></h4>
<div class="paragraph">
<p>This element configures a number of client-side interceptors which can be
configured without changing the deployments.</p>
</div>
<div class="paragraph">
<p>Each interceptor is configured in <em>&lt;interceptor&gt;</em> tag which contains the
following fields:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>module</code> - the module in which the interceptor is defined</p>
</li>
<li>
<p><code>class</code> - the class which implements the interceptor</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In order to use server interceptors you have to create a module that implements
them and place it into <em>${WILDFLY_HOME}/modules</em> directory.</p>
</div>
<div class="paragraph">
<p>Interceptor implementations must implement <em>org.jboss.ejb.client.EJBClientInterceptor</em>
interface.</p>
</div>
<div class="paragraph">
<p>Sample configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;client-interceptors&gt;</span>
        <span class="tag">&lt;interceptor</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo:FooInterceptor:1.0</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">class</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.foo.FooInterceptor</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/client-interceptors&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Sample interceptor implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">org.foo</span>;

<span class="keyword">import</span> <span class="include">org.jboss.ejb.client.EJBClientInterceptor</span>;
<span class="keyword">import</span> <span class="include">org.jboss.ejb.client.EJBClientInvocationContext</span>;

<span class="directive">public</span> <span class="type">class</span> <span class="class">FooInterceptor</span> <span class="directive">implements</span> EJBClientInterceptor {

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleInvocation(EJBClientInvocationContext context) <span class="directive">throws</span> <span class="exception">Exception</span> {
        context.sendRequest();
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="predefined-type">Object</span> handleInvocationResult(EJBClientInvocationContext context) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="keyword">return</span> context.getResult();
    }
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
References in this document to Enterprise JavaBeans(EJB) refer to the Jakarta Enterprise Beans unless otherwise noted.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Undertow"><a class="anchor" href="#Undertow"></a><a class="link" href="#Undertow">7.7. Undertow subsystem configuration</a></h3>
<div class="sidebarblock">
<div class="content">
<div class="paragraph">
<p><strong>Web subsystem was replaced in WildFly 8 with Undertow.</strong></p>
</div>
</div>
</div>
<div class="paragraph">
<p>There are two main parts to the undertow subsystem, which are server and
Servlet container configuration, as well as some ancillary items.
Advanced topics like load balancing and failover are covered on the
"High Availability Guide". The default configuration does is suitable
for most use cases and provides reasonable performance settings.</p>
</div>
<div class="paragraph">
<p><strong>Required extension:</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.wildfly.extension.undertow</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Basic subsystem configuration example:</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:undertow:13.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;buffer-cache</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">buffer-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1024</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">buffers-per-region</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1024</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-regions</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-server</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;http-listener</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;host</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">alias</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;location</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">handler</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">welcome-content</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;/host&gt;</span>
        <span class="tag">&lt;/server&gt;</span>
        <span class="tag">&lt;servlet-container</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-buffer-cache</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">stack-trace-on-error</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">local-only</span><span class="delimiter">&quot;</span></span> <span class="tag">&gt;</span>
            <span class="tag">&lt;jsp-config</span><span class="tag">/&gt;</span>
            <span class="tag">&lt;persistent-sessions</span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/servlet-container&gt;</span>
        <span class="tag">&lt;handlers&gt;</span>
            <span class="tag">&lt;file</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">welcome-content</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.home.dir}/welcome-content</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">directory-listing</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/handlers&gt;</span>
    <span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-server</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the default server to use for deployments</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-virtual-host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the default virtual host to use for deployments</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-servlet-container</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the default servlet container to use for deployments</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">instance-id</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the id of Undertow. Defaults to "${jboss.node.name}" if undefined</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="bookmark-obfuscate-session-route"></a>obfuscate-session-route</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">set this to <code>"true"</code> to indicate the
<code>instance-id</code> should be obfuscated in routing. This prevents <code>instance-id</code> from being sent across
HTTP connections when serving remote requests with the HTTP invoker.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-security-domain</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the default security domain used by web deployments</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">statistics-enabled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">set this to true to enable statistics gathering for Undertow subsystem</p></td>
</tr>
</tbody>
</table>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>When setting <a href="#bookmark-obfuscate-session-route"><code>obfuscate-session-route</code></a> to <code>"true"</code>, the server&#8217;s
<a href="#bookmark-server-name"><code>name</code></a> is used as a salt in the hashing algorithm that obfuscates the value of <code>instance-id</code>.
For that reason, it is strongly advised that the value of the server be changed from <code>"default-server"</code> to something
else, or else it would be easy to reverse engineer the obfuscated route to its original value, using <code>"default-server"</code>
bytes as the salt.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p><strong>Dependencies on other subsystems:</strong></p>
</div>
<div class="paragraph">
<p>IO Subsystem</p>
</div>
<div class="sect3">
<h4 id="buffer-cache-configuration"><a class="anchor" href="#buffer-cache-configuration"></a><a class="link" href="#buffer-cache-configuration">7.7.1. Buffer cache configuration</a></h4>
<div class="paragraph">
<p>The buffer cache is used for caching content, such as static files.
Multiple buffer caches can be configured, which allows for separate
servers to use different sized caches.</p>
</div>
<div class="paragraph">
<p>Buffers are allocated in regions, and are of a fixed size. If you are
caching many small files then using a smaller buffer size will be
better.</p>
</div>
<div class="paragraph">
<p>The total amount of space used can be calculated by multiplying the
buffer size by the number of buffers per region by the maximum number of
regions.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">  <span class="tag">&lt;buffer-caches&gt;</span>
    <span class="tag">&lt;buffer-cache</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">buffer-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1024</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">buffers-per-region</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1024</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-regions</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;/buffer-caches&gt;</span></code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">buffer-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the buffers. Smaller buffers allow space to be
utilised more effectively</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">buffers-per-region</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The numbers of buffers per region</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-regions</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of regions. This controls the maximum
amount of memory that can be used for caching</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="server-configuration"><a class="anchor" href="#server-configuration"></a><a class="link" href="#server-configuration">7.7.2. Server configuration</a></h4>
<div class="paragraph">
<p>A server represents an instance of Undertow. Basically this consists of
a set of connectors and some configured handlers.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-server</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-host</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">servlet-container</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="tag">&gt;</span></code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a id="bookmark-server-name"></a>name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the name of this server</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the virtual host that will be used if an incoming request
as no Host: header</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">servlet-container</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the servlet container that will be used by this
server, unless is is explicitly overriden by the deployment</p></td>
</tr>
</tbody>
</table>
<div class="sect4">
<h5 id="connector-configuration"><a class="anchor" href="#connector-configuration"></a><a class="link" href="#connector-configuration">Connector configuration</a></h5>
<div class="paragraph">
<p>Undertow provides HTTP, HTTPS and AJP connectors, which are configured
per server.</p>
</div>
<div class="sect5">
<h6 id="common-settings"><a class="anchor" href="#common-settings"></a><a class="link" href="#common-settings">Common settings</a></h6>
<div class="paragraph">
<p>The following settings are common to all connectors:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">allow-encoded-slash</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If a request comes in with encoded / characters (i.e. %2F), will these be decoded.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">allow-equals-in-cookie-value</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then Undertow will allow non-escaped equals characters in unquoted cookie values.
Unquoted cookie values may not contain equals characters. If present the value ends before the
equals sign. The remainder of the cookie value will be dropped.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">allow-unescaped-characters-in-url</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true Undertow will accept non-encoded characters that are disallowed by the URI specification.
This defaults to false, and in general should not be needed as most clients correctly encode characters.
Note that setting this to true can be considered a security risk, as allowing non-standard characters can
allow request smuggling attacks in some circumstances.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">always-set-keep-alive</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then a Connection: keep-alive header will be added to responses, even when it is not
strictly required by the specification.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">buffer-pipelined-data</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If we should buffer pipelined requests.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">buffer-pool</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The listeners buffer pool</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">certificate-forwarding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If certificate forwarding should be enabled. If this is enabled then the listener will take the certificate
from the SSL_CLIENT_CERT attribute. This should only be enabled if behind a proxy, and the proxy is
configured to always set these headers.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">decode-url</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then the parser will decode the URL and query parameters using the selected character
encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to
decode them into whatever charset is desired.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">disallowed-methods</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A comma separated list of HTTP methods that are not allowed</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enable-http2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables HTTP2 support for this listener</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enabled (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If the listener is enabled</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-enable-push</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If server push is enabled for this connection</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-header-table-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the header table used for HPACK compression, in bytes. This amount of memory will be allocated
per connection for compression. Larger values use more memory but may give better compression.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-initial-window-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The flow control window size that controls how quickly the client can send data to the server</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-max-concurrent-streams</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of HTTP/2 streams that can be active at any time on a single connection</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-max-frame-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The max HTTP/2 frame size</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http2-max-header-list-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of request headers the server is prepared to accept</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-buffered-request-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum size of a buffered request, in bytes. Requests are not usually buffered, the most common case is
when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order
to perform the renegotiation.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-connections</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of concurrent connections. Only values greater than 0 are allowed. For unlimited
connections simply undefine this attribute value.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-cookies</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-header-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of a http request header, in bytes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-headers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-parameters</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities.
This applies to both query parameters, and to POST data, but is not cumulative (i.e. you can potentially
have max parameters * 2 total parameters).</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-post-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum size of a post that will be accepted, in bytes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">no-request-timeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The length of time in milliseconds that the connection can be idle before it is closed by the container.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">proxy-address-forwarding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables  handling of x-forwarded-host header (and other x-forwarded-* headers) and use this header information
to set the remote address. This should only be used behind a trusted proxy that sets these headers otherwise
a remote user can spoof their IP address.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">proxy-protocol</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then the listener will use the proxy protocol v1, as defined by
<a href="https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt" class="bare">https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt</a>. This option MUST only be enabled for listeners
that are behind a load balancer that supports the same protocol.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">read-timeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure a read timeout for a socket, in milliseconds.  If the given amount of time elapses without a
successful read taking place, the socket&#8217;s next read will throw a {@link ReadTimeoutException}.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">receive-buffer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The receive buffer size, in bytes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">record-request-start-time</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then Undertow will record the request start time, to allow for request time to be logged.
This has a small but measurable performance impact</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">request-parse-timeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum amount of time (in milliseconds) that can be spent parsing the request</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">require-host-http11</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Require that all HTTP/1.1 requests have a 'Host' header, as per the RFC. IF the request does not include
this header it will be rejected with a 403.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">resolve-peer-address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables host dns lookup</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">rfc6265-cookie-validation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If cookies should be validated to ensure they comply with RFC6265.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">secure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then requests that originate from this listener are marked as secure, even if the request
is not using HTTPS.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">send-buffer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The send buffer size, in bytes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">socket-binding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The listener socket binding</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">tcp-backlog</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure a server with the specified backlog.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">tcp-keep-alive</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">url-charset</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">URL charset</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">worker</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The listeners XNIO worker</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">write-timeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configure a write timeout for a socket, in milliseconds.  If the given amount of time
elapses without a successful write taking place, the socket&#8217;s next write will throw
a {@link WriteTimeoutException}.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="http-connector"><a class="anchor" href="#http-connector"></a><a class="link" href="#http-connector">HTTP Connector</a></h6>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;http-listener</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>  <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">redirect-socket</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this listener is supporting non-SSL requests, and a request is received for which a matching
&lt;security-constraint&gt; requires SSL transport, undertow will automatically redirect the request to the
socket binding port specified here.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="https-listener"><a class="anchor" href="#https-listener"></a><a class="link" href="#https-listener">HTTPS listener</a></h6>
<div class="paragraph">
<p>Https listener provides secure access to the server. The most important
configuration option is ssl-context which cross references a pre-configured
SSL Context instance.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;https-listener</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">https</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">https</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">ssl-context</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">applicationSSC</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">enable-http2</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enable-spdy (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables SPDY support for this listener. This has been deprecated and has no effect, HTTP/2 should be used instead</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enabled-cipher-suites (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Where an SSLContext is referenced it should be configured with the cipher suites to be supported.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enabled-protocols (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Configures SSL protocols</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">security-realm (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The listeners security realm</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ssl-context</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reference to the SSLContext to be used by this listener.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ssl-session-cache-size (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of active SSL sessions</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ssl-session-timeout (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The timeout for SSL sessions, in seconds</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">verify-client (Deprecated)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The desired SSL client authentication mode for SSL channels</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="ajp-listener"><a class="anchor" href="#ajp-listener"></a><a class="link" href="#ajp-listener">AJP listener</a></h6>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;ajp-listener</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ajp</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="host-configuration"><a class="anchor" href="#host-configuration"></a><a class="link" href="#host-configuration">Host configuration</a></h5>
<div class="paragraph">
<p>The host element corresponds to a virtual host.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The virtual host name</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">alias</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A whitespace separated list of additional host names that should
be matched</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-web-module</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of a deployment that should be used to
serve up requests that do not match anything.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">queue-requests-on-start</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If requests should be queued on start for this host. If this is set to false the default
response code will be returned instead.</p>
<p class="tableblock">Note: If a <a href="#non-graceful-startup">Non-graceful Startup</a> is requested, and the queue-requests-on-start attribute is not set, requests will NOT be
queued despite the default value of true for the property. In the instance of a non-graceful startup, non-queued requests
are required. However, if non-graceful is configured, but queue-requests-on-start is explicitly set to true, then requests
will be queued, effectively disabling the non-graceful mode for requests to that host.</p></td>
</tr>
</tbody>
</table>
<div class="sect5">
<h6 id="console-access-logging"><a class="anchor" href="#console-access-logging"></a><a class="link" href="#console-access-logging">Console Access Logging</a></h6>
<div class="paragraph">
<p>Each host allows for access logging to the console which writes structured data in JSON format. This only writes to
<code>stdout</code> and is a single line of JSON structured data.</p>
</div>
<div class="paragraph">
<p>The <code>attributes</code> management model attribute is used to determine which exchange attributes should be logged. This is
similar to the <code>pattern</code> used for traditional access logging. The main difference being since the data is structured
the ability to use defined keys is essential.</p>
</div>
<div class="paragraph">
<p>A <code>metadata</code> attribute also exists which allows extra metadata to be added to the output. The value of the attribute is
a set of arbitrary key/value pairs. The values can include management model expressions, which must be resolvable when
the console access log service is started. The value is resolved once per start or reload of the server.</p>
</div>
<div class="sect6">
<h7 id="cli-examples"><a class="anchor" href="#cli-examples"></a><a class="link" href="#cli-examples">CLI Examples</a></h7>
<div class="listingblock">
<div class="title">add-console-access-logging.cli</div>
<div class="content">
<pre>/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add</pre>
</div>
</div>
<div class="listingblock">
<div class="title">complex-add-console-access-logging.cli</div>
<div class="content">
<pre>/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add(metadata={"@version"="1", "qualifiedHostName"=${jboss.qualified.host.name:unknown}}, attributes={bytes-sent={}, date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:ssSSS"}, remote-host={}, request-line={}, response-header={key-prefix="responseHeader", names=["Content-Type"]}, response-code={}, remote-user={}})</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{
    <span class="key"><span class="delimiter">&quot;</span><span class="content">eventSource</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">web-access</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">hostName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">@version</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">qualifiedHostName</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">localhost.localdomain</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">bytesSent</span><span class="delimiter">&quot;</span></span>:<span class="integer">1504</span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">@timestamp</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2019-05-02T11:57:37123</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">remoteHost</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">remoteUser</span><span class="delimiter">&quot;</span></span>:<span class="value">null</span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">requestLine</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">GET / HTTP/2.0</span><span class="delimiter">&quot;</span></span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">responseCode</span><span class="delimiter">&quot;</span></span>:<span class="integer">200</span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">responseHeaderContent-Type</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">text/html</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The above JSON is formatted only for readability. The output will be on a single line.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="servlet-container-configuration"><a class="anchor" href="#servlet-container-configuration"></a><a class="link" href="#servlet-container-configuration">7.7.3. Servlet container configuration</a></h4>
<div class="paragraph">
<p>The servlet-container element corresponds to an instance of an Undertow
Servlet container. Most servers will only need a single servlet
container, however there may be cases where it makes sense to define
multiple containers (in particular if you want applications to be
isolated, so they cannot dispatch to each other using the
RequestDispatcher. You can also use multiple Servlet containers to serve
different applications from the same context path on different virtual
hosts).</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">allow-non-standard-wrappers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The Servlet specification requires
applications to only wrap the request/response using wrapper classes
that extend from the ServletRequestWrapper and ServletResponseWrapper
classes. If this is set to true then this restriction is relaxed.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-buffer-cache</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The buffer cache that is used to cache static
resources in the default Servlet.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stack-trace-on-error</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Can be either all, none, or local-only. When set
to none Undertow will never display stack traces. When set to All
Undertow will always display them (not recommended for production use).
When set to local-only Undertow will only display them for requests from
local addresses, where there are no headers to indicate that the request
has been proxied. Note that this feature means that the Undertow error
page will be displayed instead of the default error page specified in
web.xml.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">default-encoding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The default encoding to use for requests and
responses.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">use-listener-encoding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is true then the default encoding will
be the same as that used by the listener that received the request.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">preserve-path-on-forward</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this is <code>true</code>, the return values of the
<code>getServletPath()</code>, <code>getRequestURL()</code> and <code>getRequestURI()</code> methods from
 <code>HttpServletRequest</code> will be unchanged following a
 <code>RequestDispatcher.forward()</code> call, and point to the original resource requested.
If <code>false</code>, following the <code>RequestDispatcher.forward()</code> call, they will
point to the resource being forwarded to.</p></td>
</tr>
</tbody>
</table>
<div class="sect4">
<h5 id="Jakarta-Server-Pages-configuration"><a class="anchor" href="#Jakarta-Server-Pages-configuration"></a><a class="link" href="#Jakarta-Server-Pages-configuration">Jakarta Server Pages configuration</a></h5>

</div>
<div class="sect4">
<h5 id="session-cookie-configuration"><a class="anchor" href="#session-cookie-configuration"></a><a class="link" href="#session-cookie-configuration">Session Cookie Configuration</a></h5>
<div class="paragraph">
<p>This allows you to change the attributes of the session cookie.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The cookie name</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">domain</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The cookie domain</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">comment</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The cookie comment</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">http-only</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If the cookie is HTTP only</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">secure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If the cookie is marked secure</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-age</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The max age of the cookie</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="persistent-session-configuration"><a class="anchor" href="#persistent-session-configuration"></a><a class="link" href="#persistent-session-configuration">Persistent Session Configuration</a></h5>
<div class="paragraph">
<p>Persistent sessions allow session data to be saved across redeploys and
restarts. This feature is enabled by adding the persistent-sessions
element to the server config. This is mostly intended to be a
development time feature.</p>
</div>
<div class="paragraph">
<p>If the path is not specified then session data is stored in memory, and
will only be persistent across redeploys, rather than restarts.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The path to the persistent sessions data</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">relative-to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The location that the path is relevant to</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="Undertow_AJP_listeners"><a class="anchor" href="#Undertow_AJP_listeners"></a><a class="link" href="#Undertow_AJP_listeners">7.7.4. AJP listeners</a></h4>
<div class="paragraph">
<p>The AJP listeners are child resources of the subsystem undertow. They
are used with mod_jk, mod_proxy and mod_cluster of the Apache httpd
front-end. Each listener does reference a particular socket binding:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=undertow/server=default-server:read-children-names(child-type=ajp-listener)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        &quot;ajp-listener&quot;,
    ]
}
 
[standalone@localhost:9999 /] /subsystem=undertow/server=default-server/ajp-listener=*:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;enabled&quot; =&gt; &quot;true&quot;,
        &quot;scheme&quot; =&gt; &quot;http&quot;,
        &quot;socket-binding&quot; =&gt; &quot;ajp&quot;,
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Creating a new <code>ajp-listener</code> requires you to declare a new
<code>socket binding</code> first:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The newly created, unused socket binding can then be used to create a
new connector configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=undertow/server=default-server/ajp-listener=myListener:add(socket-binding=ajp, scheme=http, enabled=true)</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Undertow_using_as_a_Load_Balancer"><a class="anchor" href="#Undertow_using_as_a_Load_Balancer"></a><a class="link" href="#Undertow_using_as_a_Load_Balancer">7.7.5. Using WildFly as a Load Balancer</a></h4>
<div class="paragraph">
<p>WildFly 10 added support for using the Undertow subsystem as a load
balancer. WildFly supports two different approaches, you can either
define a static load balancer, and specify the back end hosts in your
configuration, or use it as a mod_cluster frontend, and use mod_cluster
to dynamically update the hosts.</p>
</div>
<div class="sect4">
<h5 id="general-overview"><a class="anchor" href="#general-overview"></a><a class="link" href="#general-overview">General Overview</a></h5>
<div class="paragraph">
<p>WildFly uses Undertow&#8217;s proxy capabilities to act as a load balancer.
Undertow will connect to the back end servers using its built in client,
and proxies requests.</p>
</div>
<div class="paragraph">
<p>The following protocols are supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>http</code></p>
</li>
<li>
<p><code>ajp</code></p>
</li>
<li>
<p><code>http2</code></p>
</li>
<li>
<p><code>h2c</code> (clear text HTTP2)<br>
Of these protocols h2c should give the best performance, if the back end
servers support it.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The Undertow proxy uses async IO, the only threads that are involved in
the request is the IO thread that is responsible for the connection. The
connection to the back end server is made from the same thread, which
removes the need for any thread safety constructs.<br>
If both the front and back end servers support server push, and HTTP2 is
in use then the proxy also supports pushing responses to the client. In
cases where proxy and backend are capable of server push, but the client
does not support it the server will send a <code>X-Disable-Push</code> header to let
the backend know that it should not attempt to push for this request.</p>
</div>
<div class="sect5">
<h6 id="load-balancer-server-profiles"><a class="anchor" href="#load-balancer-server-profiles"></a><a class="link" href="#load-balancer-server-profiles">Load balancer server profiles</a></h6>
<div class="paragraph">
<p>WildFly 11 added load balancer profiles for both standalone and domain modes.</p>
</div>
<div class="sect6">
<h7 id="example-start-standalone-load-balancer"><a class="anchor" href="#example-start-standalone-load-balancer"></a><a class="link" href="#example-start-standalone-load-balancer">Example: Start standalone load balancer</a></h7>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code># configure correct path to WildFly installation
WILDFLY_HOME=/path/to/wildfly

# configure correct IP of the node
MY_IP=192.168.1.1

# run the load balancer profile
$WILDFLY_HOME/bin/standalone.sh -b $MY_IP -bprivate $MY_IP -c standalone-load-balancer.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>It&#8217;s highly recommended to use private/internal network for communication between load balancer and nodes.
To do this set the correct IP address to the <code>private</code> interface (<code>-bprivate</code> argument).</p>
</div>
</div>
<div class="sect6">
<h7 id="example-start-worker-node"><a class="anchor" href="#example-start-worker-node"></a><a class="link" href="#example-start-worker-node">Example: Start worker node</a></h7>
<div class="paragraph">
<p>Run the server with the HA (or Full HA) profile, which has <code>mod_cluster</code> component included.
If the UDP multicast is working in your environment, the workers should work out of the box without any change.
If it&#8217;s not the case, then configure the IP address of the load balancer statically.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code># configure correct path to WildFly installation
WILDFLY_HOME=/path/to/wildfly
# configure correct IP of the node
MY_IP=192.168.1.2

# Configure static load balancer IP address.
# This is necessary when UDP multicast doesn't work in your environment.
LOAD_BALANCER_IP=192.168.1.1
$WILDFLY_HOME/bin/jboss-cli.sh &lt;&lt;EOT

embed-server -c=standalone-ha.xml
/subsystem=modcluster/proxy=default:write-attribute(name=advertise, value=false)
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=proxy1:add(host=$LOAD_BALANCER_IP, port=8090)
/subsystem=modcluster/proxy=default:list-add(name=proxies, value=proxy1)
EOT

# start the woker node with HA profile
$WILDFLY_HOME/bin/standalone.sh -c standalone-ha.xml -b $MY_IP -bprivate $MY_IP</code></pre>
</div>
</div>
<div class="paragraph">
<p>Again, to make it safe, users should configure private/internal IP address into <code>MY_IP</code> variable.</p>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="using-wildfly-as-a-static-load-balancer"><a class="anchor" href="#using-wildfly-as-a-static-load-balancer"></a><a class="link" href="#using-wildfly-as-a-static-load-balancer">Using WildFly as a static load balancer</a></h5>
<div class="paragraph">
<p>To use WildFly as a static load balancer the first step is to create a
proxy handler in the Undertow subsystem. For the purposes of this
example we are going to assume that our load balancer is going to load
balance between two servers, <code>sv1.foo.com</code> and <code>sv2.foo.com</code>, and will be
using the AJP protocol.</p>
</div>
<div class="paragraph">
<p>The first step is to add a reverse proxy handler to the Undertow
subsystem:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=undertow/configuration=handler/reverse-proxy=my-handler:add()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then we need to define <code>outbound-socket-binding</code>-s for remote hosts:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host1:add(host=sv1.foo.com, port=8009)
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host2:add(host=sv2.foo.com, port=8009)</code></pre>
</div>
</div>
<div class="paragraph">
<p>and than we add them as hosts to reverse proxy handler:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host1:add(outbound-socket-binding=remote-host1, scheme=ajp, instance-id=myroute, path=/test)
/subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host2:add(outbound-socket-binding=remote-host2, scheme=ajp, instance-id=myroute, path=/test)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now we need to actually add the reverse proxy to a location.
Assuming we are serving the path <code>/app</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=undertow/server=default-server/host=default-host/location=\/app:add(handler=my-handler)</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is all there is to it. If you point your browser to <a href="http://localhost:8080/app" class="bare">http://localhost:8080/app</a>
you should be able to see the proxied content.</p>
</div>
<div class="paragraph">
<p>The full details of all configuration options available can be found in
the <a href="wildscribe/subsystem/undertow/index.html" target="_blank" rel="noopener">subsystem reference</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Messaging"><a class="anchor" href="#Messaging"></a><a class="link" href="#Messaging">7.8. Messaging configuration</a></h3>
<div class="paragraph">
<p>The Jakarta Messaging server configuration is done through the <em>messaging-activemq</em>
subsystem. In this chapter we are going outline the frequently used
configuration options. For a more detailed explanation please consult
the Artemis user guide (See "Component Reference").</p>
</div>
<div class="sect3">
<h4 id="required-extension-messaging"><a class="anchor" href="#required-extension-messaging"></a><a class="link" href="#required-extension-messaging">7.8.1. Required Extension</a></h4>
<div class="paragraph">
<p>The configuration options discussed in this section assume that the the
<code>org.wildfly.extension.messaging-activemq</code> extension is present in your
configuration. This extension is not included in the standard
<code>standalone.xml</code> and <code>standalone-ha.xml</code> configurations included in the
WildFly distribution. It is, however, included with the
<code>standalone-full.xml</code> and <code>standalone-full-ha.xml</code> configurations.</p>
</div>
<div class="paragraph">
<p>You can add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.messaging-activemq"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /]/extension=org.wildfly.extension.messaging-activemq:add</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="connectors"><a class="anchor" href="#connectors"></a><a class="link" href="#connectors">7.8.2. Connectors</a></h4>
<div class="paragraph">
<p>There are three kind of connectors that can be used to connect to
WildFly Jakarta Messaging Server</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>invm-connector</code> can be used by a local client (i.e. one running in
the same JVM as the server)</p>
</li>
<li>
<p><code>netty-connector</code> can be used by a remote client (and uses Netty over
TCP for the communication)</p>
</li>
<li>
<p><code>http-connector</code> can be used by a remote client (and uses Undertow Web
Server to upgrade from a HTTP connection)</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="Jakarta-Messaging-connection-factories"><a class="anchor" href="#Jakarta-Messaging-connection-factories"></a><a class="link" href="#Jakarta-Messaging-connection-factories">7.8.3. Jakarta Messaging Connection Factories</a></h4>
<div class="paragraph">
<p>There are three kinds of <em>basic</em> Jakarta Messaging <code>connection-factory</code> that depends
on the type of connectors that is used.</p>
</div>
<div class="paragraph">
<p>There is also a <code>pooled-connection-factory</code> which is special in that it
is essentially a configuration facade for <em>both</em> the inbound and
outbound connectors of the the Artemis Jakarta Connectors Resource Adapter. An MDB can
be configured to use a <code>pooled-connection-factory</code> (e.g. using
<code>@ResourceAdapter</code>). In this context, the MDB leverages the <em>inbound
connector</em> of the Artemis Jakarta Connectors RA. Other kinds of clients can look up the
pooled-connection-factory in JNDI (or inject it) and use it to send
messages. In this context, such a client would leverage the <em>outbound
connector</em> of the Artemis Jakarta Connectors RA. A <code>pooled-connection-factory</code> is also
special because:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It is only available to local clients, although it can be configured
to point to a remote server.</p>
</li>
<li>
<p>As the name suggests, it is pooled and therefore provides superior
performance to the clients which are able to use it. The pool size can
be configured via the <code>max-pool-size</code> and <code>min-pool-size</code> attributes.</p>
</li>
<li>
<p>It should only be used to <em>send</em> (i.e. produce) messages when looked
up in JNDI or injected.</p>
</li>
<li>
<p>It can be configured to use specific security credentials via the
<code>user</code> and <code>password</code> attributes. This is useful if the remote server to
which it is pointing is secured.</p>
</li>
<li>
<p>Resources acquired from it will be automatically enlisted any on-going
Jakarta Transactions. If you want to send a message from an Jakarta Enterprise Beans using CMT
then this is likely the connection factory you want to use so the send
operation will be atomically committed along with the rest of the Jakarta Enterprise Beans&#8217;s
transaction operations.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To be clear, the <em>inbound connector</em> of the Artemis Jakarta Connectors RA (which is for
consuming messages) is only used by MDBs and other Jakarta Connectors based components.
It is not available to traditional clients.</p>
</div>
<div class="paragraph">
<p>Both a <code>connection-factory</code> and a <code>pooled-connection-factory</code> reference
a <code>connector</code> declaration.</p>
</div>
<div class="paragraph">
<p>A <code>netty-connector</code> is associated with a <code>socket-binding</code> which tells
the client using the <code>connection-factory</code> where to connect.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A <code>connection-factory</code> referencing a <code>netty-connector</code> is suitable to
be used by a <em>remote</em> client to send messages to or receive messages
from the server (assuming the connection-factory has an appropriately
exported <code>entry</code>).</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> looked up in JNDI or injected which is
referencing a <code>netty-connector</code> is suitable to be used by a <em>local</em>
client to send messages to a remote server granted the <code>socket-binding</code>
references an <code>outbound-socket-binding</code> pointing to the remote server in
question.</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> used by an MDB which is referencing a
<code>remote-connector</code> is suitable to consume messages from a remote server
granted the <code>socket-binding</code> references an <code>outbound-socket-binding</code>
pointing to the remote server in question.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>An <code>in-vm-connector</code> is associated with a <code>server-id</code> which tells the
client using the <code>connection-factory</code> where to connect (since multiple
Artemis servers can run in a single JVM).</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A <code>connection-factory</code> referencing an <code>in-vm-connector</code> is suitable to
be used by a <em>local</em> client to either send messages to or receive
messages from a local server.</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> looked up in JNDI or injected which is
referencing an <code>in-vm-connector</code> is suitable to be used by a <em>local</em>
client only to send messages to a local server.</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> used by an MDB which is referencing an
<code>in-vm-connector</code> is suitable only to consume messages from a local
server.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A <code>http-connector</code> is associated with the <code>socket-binding</code> that
represents the HTTP socket (by default, named <code>http</code>).</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A <code>connection-factory</code> referencing a <code>http-connector</code> is suitable to
be used by a remote client to send messages to or receive messages from
the server by connecting to its HTTP port before upgrading to the
messaging protocol.</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> referencing a <code>http-connector</code> is
suitable to be used by a local client to send messages to a remote
server granted the <code>socket-binding</code> references an
<code>outbound-socket-binding</code> pointing to the remote server in question.</p>
</li>
<li>
<p>A <code>pooled-connection-factory</code> used by an MDB which is referencing a
<code>http-connector</code> is suitable only to consume messages from a remote
server granted the <code>socket-binding</code> references an
<code>outbound-socket-binding</code> pointing to the remote server in question.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <code>entry</code> declaration of a <code>connection-factory</code> or a
<code>pooled-connection-factory</code> specifies the JNDI name under which the
factory will be exposed. Only JNDI names bound in the
<code>"java:jboss/exported"</code> namespace are available to remote clients. If a
<code>connection-factory</code> has an entry bound in the <code>"java:jboss/exported"</code>
namespace a remote client would look-up the <code>connection-factory</code> using
the text <em>after</em> <code>"java:jboss/exported"</code>. For example, the "
<code>RemoteConnectionFactory`" is bound by default to
`"java:jboss/exported/jms/RemoteConnectionFactory"</code> which means a remote
client would look-up this <code>connection-factory</code> using "
<code>jms/RemoteConnectionFactory`". A `pooled-connection-factory</code> should
<em>not</em> have any <code>entry</code> bound in the " <code>java:jboss/exported`" namespace
because a `pooled-connection-factory</code> is not suitable for remote
clients.</p>
</div>
<div class="paragraph">
<p>Since Jakarta Messaging 2.0, a default Jakarta Messaging connection factory is accessible to Jakarta EE
applications under the JNDI name <code>java:comp/DefaultJMSConnectionFactory.</code>
The WildFly messaging subsystem defines a <code>pooled-connection-factory</code> that
is used to provide this default connection factory. Any parameter change
on this <code>pooled-connection-factory</code> will be take into account by any EE
application looking the default Jakarta Messaging provider under the JNDI name
<code>java:comp/DefaultJMSConnectionFactory.</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        [...]
        <span class="tag">&lt;http-connector</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http-connector</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">endpoint</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http-acceptor</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;http-connector</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http-connector-throughput</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">endpoint</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http-acceptor-throughput</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;param</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">batch-delay</span><span class="delimiter">&quot;</span></span>
                   <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">50</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/http-connector&gt;</span>
        <span class="tag">&lt;in-vm-connector</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">in-vm</span><span class="delimiter">&quot;</span></span>
                         <span class="attribute-name">server-id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      [...]
      <span class="tag">&lt;connection-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">InVmConnectionFactory</span><span class="delimiter">&quot;</span></span>
                            <span class="attribute-name">connectors</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">in-vm</span><span class="delimiter">&quot;</span></span>
                            <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:/ConnectionFactory</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
      <span class="tag">&lt;pooled-connection-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">activemq-ra</span><span class="delimiter">&quot;</span></span>
                            <span class="attribute-name">transaction</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">xa</span><span class="delimiter">&quot;</span></span>
                            <span class="attribute-name">connectors</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">in-vm</span><span class="delimiter">&quot;</span></span>
                            <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:/JmsXA java:jboss/DefaultJMSConnectionFactory</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      [...]
   <span class="tag">&lt;/server&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone-full.xml)~</p>
</div>
</div>
<div class="sect3">
<h4 id="Jakarta-Messaging-queues-and-topics"><a class="anchor" href="#Jakarta-Messaging-queues-and-topics"></a><a class="link" href="#Jakarta-Messaging-queues-and-topics">7.8.4. Jakarta Messaging Queues and Topics</a></h4>
<div class="paragraph">
<p>Jakarta Messaging queues and topics are sub resources of the messaging-actively
subsystem. One can define either a <code>jms-queue</code> or <code>jms-topic</code>. Each
destination <em>must</em> be given a <code>name</code> and contain at least one entry in
its <code>entries</code> element (separated by whitespace).</p>
</div>
<div class="paragraph">
<p>Each entry refers to a JNDI name of the queue or topic. Keep in mind
that any <code>jms-queue</code> or <code>jms-topic</code> which needs to be accessed by a
remote client needs to have an entry in the "java:jboss/exported"
namespace. As with connection factories, if a <code>jms-queue</code> or or
<code>jms-topic</code> has an entry bound in the "java:jboss/exported" namespace a
remote client would look it up using the text <em>after</em>
<code>"java:jboss/exported`". For example, the following `jms-queue</code>
"testQueue" is bound to "java:jboss/exported/jms/queue/test" which means
a remote client would look-up this \{{kms-queue} using
"jms/queue/test". A local client could look it up using
"java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more
simply "jms/queue/test":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    [...]
    <span class="tag">&lt;jms-queue</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testQueue</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms/queue/test java:jboss/exported/jms/queue/test</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;jms-topic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testTopic</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms/topic/test java:jboss/exported/jms/topic/test</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone-full.xml)~</p>
</div>
<div class="paragraph">
<p>Jakarta Messaging endpoints can easily be created through the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] jms-queue add --queue-address=myQueue --entries=queues/myQueue</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/jms-queue=myQueue:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;durable&quot; =&gt; true,
        &quot;entries&quot; =&gt; [&quot;queues/myQueue&quot;],
        &quot;selector&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Pausing and resuming Queues and Topics</p>
</div>
<div class="paragraph">
<p>When a queue is paused, it will receive messages but will not deliver them. When it&#8217;s resumed, it&#8217;ll begin delivering the queued messages, if any.
When a topic is paused, it will receive messages but will not deliver them. Newly added subscribers will be paused too until the topic is resumed. When it is resumed, delivering will occur again. The <code>persist</code> parameter ensure that the topic stays paused on the restart of the server.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/jms-queue=myQueue:pause()</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/jms-topic=myTopic:pause()</code></pre>
</div>
</div>
<div class="paragraph">
<p>A number of additional commands to maintain the Jakarta Messaging subsystem are
available as well:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] jms-queue --help --commands
add
...
remove
To read the description of a specific command execute 'jms-queue command_name --help'.</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="dead-letter-redelivery"><a class="anchor" href="#dead-letter-redelivery"></a><a class="link" href="#dead-letter-redelivery">7.8.5. Dead Letter &amp; Redelivery</a></h4>
<div class="paragraph">
<p>Some of the settings are applied against an address wild card instead of
a specific messaging destination. The dead letter queue and redelivery
settings belong into this group:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      [...]
      <span class="tag">&lt;address-setting</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">#</span><span class="delimiter">&quot;</span></span>
                       <span class="attribute-name">dead-letter-address</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms.queue.DLQ</span><span class="delimiter">&quot;</span></span>
                       <span class="attribute-name">expiry-address</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms.queue.ExpiryQueue</span><span class="delimiter">&quot;</span></span>
                       <span class="error">[</span><span class="attribute-name">...</span><span class="error">]</span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone-full.xml)~</p>
</div>
</div>
<div class="sect3">
<h4 id="security-settings-for-artemis-addresses-and-Jakarta-Messaging-destinations"><a class="anchor" href="#security-settings-for-artemis-addresses-and-Jakarta-Messaging-destinations"></a><a class="link" href="#security-settings-for-artemis-addresses-and-Jakarta-Messaging-destinations">7.8.6. Security Settings for Artemis addresses and Jakarta Messaging destinations</a></h4>
<div class="paragraph">
<p>Security constraints are matched against an address wildcard, similar to
the DLQ and redelivery settings.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      [...]
      <span class="tag">&lt;security-setting</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">#</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
          <span class="tag">&lt;role</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">guest</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">send</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">consume</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">create-non-durable-queue</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">delete-non-durable-queue</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone-full.xml)~</p>
</div>
</div>
<div class="sect3">
<h4 id="security-domain-for-users"><a class="anchor" href="#security-domain-for-users"></a><a class="link" href="#security-domain-for-users">7.8.7. Security Domain for Users</a></h4>
<div class="paragraph">
<p>By default, Artemis will use the " <code>ApplicationDomain`" Elytron security
domain. This domain is used to authenticate users making connections to Artemis
and then they are authorized to perform specific functions based on their
role(s) and the `security-settings</code> described above. This domain can be
changed by using the <code>security-domain</code>, e.g.:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;security</span> <span class="attribute-name">elytron-domain</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mySecurityDomain</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
      [...]</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="cluster-authentication"><a class="anchor" href="#cluster-authentication"></a><a class="link" href="#cluster-authentication">7.8.8. Cluster Authentication</a></h4>
<div class="paragraph">
<p>If the Artemis server is configured to be clustered, it will use the
<code>cluster</code> 's <code>user</code> and <code>password</code> attributes to connect to other
Artemis nodes in the cluster.</p>
</div>
<div class="paragraph">
<p>If you do not change the default value of &lt;cluster-password&gt;, Artemis
will fail to authenticate with the error:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>HQ224018: Failed to create session: HornetQExceptionerrorType=CLUSTER_SECURITY_EXCEPTION message=HQ119099: Unable to authenticate cluster user: HORNETQ.CLUSTER.ADMIN.USER</code></pre>
</div>
</div>
<div class="paragraph">
<p>To prevent this error, you must specify a value for
<code>&lt;cluster-password&gt;</code>. It is possible to encrypt this value by as an encrypted
expression by referring to the Elytron documentation.</p>
</div>
<div class="paragraph">
<p>Alternatively, you can use the system property
jboss.messaging.cluster.password to specify the cluster password from
the command line.</p>
</div>
</div>
<div class="sect3">
<h4 id="deployment-of--jms.xml-files"><a class="anchor" href="#deployment-of--jms.xml-files"></a><a class="link" href="#deployment-of--jms.xml-files">7.8.9. Deployment of -jms.xml files</a></h4>
<div class="paragraph">
<p>Starting with WildFly 27, you have the ability to deploy a -jms.xml file
defining Jakarta Messaging destinations, e.g.:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;messaging-deployment</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:messaging-activemq-deployment:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;jms-destinations&gt;</span>
         <span class="tag">&lt;jms-queue</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sample</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;entry</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms/queue/sample</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;entry</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/queue/sample</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
         <span class="tag">&lt;/jms-queue&gt;</span>
      <span class="tag">&lt;/jms-destinations&gt;</span>
   <span class="tag">&lt;/server&gt;</span>
<span class="tag">&lt;/messaging-deployment&gt;</span></code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
This feature <strong>is primarily intended for development</strong> as destinations
deployed this way can not be managed with any of the provided management
tools (e.g. console, CLI, etc).
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="Jakarta-Messaging-bridge"><a class="anchor" href="#Jakarta-Messaging-bridge"></a><a class="link" href="#Jakarta-Messaging-bridge">7.8.10. Jakarta Messaging Bridge</a></h4>
<div class="paragraph">
<p>The function of a Jakarta Messaging bridge is to consume messages from a source Jakarta Messaging
destination, and send them to a target Jakarta Messaging destination. Typically either
the source or the target destinations are on different servers.
The bridge can also be used to bridge messages from other non Artemis
messaging servers, as long as they are JMS 1.1 compliant.</p>
</div>
<div class="paragraph">
<p>The Jakarta Messaging Bridge is provided by the Artemis project. For a detailed
description of the available configuration properties, please consult
the project documentation.</p>
</div>
<div class="sect4">
<h5 id="modules-for-other-messaging-brokers"><a class="anchor" href="#modules-for-other-messaging-brokers"></a><a class="link" href="#modules-for-other-messaging-brokers">Modules for other messaging brokers</a></h5>
<div class="paragraph">
<p>Source and target Jakarta Messaging resources (destination and connection factories)
are looked up using JNDI.
If either the source or the target resources are managed by another
messaging server than WildFly, the required client classes must be
bundled in a module. The name of the module must then be declared when
the Jakarta Messaging Bridge is configured.</p>
</div>
<div class="paragraph">
<p>The use of a Jakarta Messaging bridges with any messaging provider will require to
create a module containing the jar of this provider.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s suppose we want to use an hypothetical messaging provider named
AcmeMQ. We want to bridge messages coming from a source AcmeMQ
destination to a target destination on the local WildFly messaging
server. To lookup AcmeMQ resources from JNDI, 2 jars are required,
acmemq-1.2.3.jar, mylogapi-0.0.1.jar (please note these jars do not
exist, this is just for the example purpose). We must <em>not</em> include a
Jakarta Messaging jar since it will be provided by a WildFly module directly.</p>
</div>
<div class="paragraph">
<p>To use these resources in a Jakarta Messaging bridge, we must bundle them in a WildFly
module:</p>
</div>
<div class="paragraph">
<p>in JBOSS_HOME/modules, we create the layout:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>modules/
`-- org
    `-- acmemq
        `-- main
            |-- acmemq-1.2.3.jar
            |-- mylogapi-0.0.1.jar
            `-- module.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>We define the module in <code>module.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;module</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:module:1.9</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.acmemq</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;properties&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.api</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">private</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/properties&gt;</span>
 
 
    <span class="tag">&lt;resources&gt;</span>
        <span class="comment">&lt;!-- insert resources required to connect to the source or target   --&gt;</span>
        <span class="comment">&lt;!-- messaging brokers if it not another WildFly instance           --&gt;</span>
        <span class="tag">&lt;resource-root</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">acmemq-1.2.3.jar</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
        <span class="tag">&lt;resource-root</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mylogapi-0.0.1.jar</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/resources&gt;</span>
 
 
    <span class="tag">&lt;dependencies&gt;</span>
       <span class="comment">&lt;!-- add the dependencies required by messaging Bridge code                --&gt;</span>
       <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">javax.api</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span> <span class="comment">&lt;!-- deprecated --&gt;</span>
       <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jakarta.jms.api</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
       <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jakarta.transaction.api</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.remote-naming</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="comment">&lt;!-- we depend on org.apache.activemq.artemis module since we will send messages to  --&gt;</span>
       <span class="comment">&lt;!-- the Artemis server embedded in the local WildFly instance       --&gt;</span>
       <span class="tag">&lt;module</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.apache.activemq.artemis</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/dependencies&gt;</span>
<span class="tag">&lt;/module&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">Configuration</a></h5>
<div class="paragraph">
<p>A Jakarta Messaging bridge is defined inside a <code>jms-bridge</code> section of the
<code>messaging-activemq</code> subsystem in the XML configuration files.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;jms-bridge</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">myBridge</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.acmemq</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;source</span> <span class="attribute-name">connection-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ConnectionFactory</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">destination</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">sourceQ</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">user</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">user1</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">pwd1</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">quality-of-service</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">AT_MOST_ONCE</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">failure-retry-interval</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">500</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">max-retries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">max-batch-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">500</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">max-batch-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">500</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">add-messageID-in-header</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
         <span class="tag">&lt;source-context&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.factory.initial</span><span class="delimiter">&quot;</span></span>
                      <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.acmemq.jndi.AcmeMQInitialContextFactory</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java.naming.provider.url</span><span class="delimiter">&quot;</span></span>
                      <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">tcp://127.0.0.1:9292</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
         <span class="tag">&lt;/source-context&gt;</span>
      <span class="tag">&lt;/source&gt;</span>
      <span class="tag">&lt;target</span> <span class="attribute-name">connection-factory</span><span class="error">&quot;</span><span class="error">/</span><span class="attribute-name">jms</span><span class="error">/</span><span class="attribute-name">invmTargetCF</span><span class="error">&quot;</span>
              <span class="attribute-name">destination</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/jms/targetQ</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
      <span class="tag">&lt;/target&gt;</span>
   <span class="tag">&lt;/jms-bridge&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>source</code> and <code>target</code> sections contain the name of the Jakarta Messaging resource
( <code>connection-factory</code> and <code>destination</code>) that will be looked up in
JNDI.
It optionally defines the <code>user</code> and <code>password</code> credentials. If they are
set, they will be passed as arguments when creating the Jakarta Messaging connection
from the looked up ConnectionFactory.
It is also possible to define JNDI context properties in the
<code>source-context</code> and <code>target-context</code> sections. If these sections are
absent, the Jakarta Messaging resources will be looked up in the local WildFly
instance (as it is the case in the <code>target</code> section in the example
above).</p>
</div>
</div>
<div class="sect4">
<h5 id="management-commands"><a class="anchor" href="#management-commands"></a><a class="link" href="#management-commands">Management commands</a></h5>
<div class="paragraph">
<p>A Jakarta Messaging Bridge can also be managed using the WildFly command line
interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging/jms-bridge=myBridge/:add(module=&quot;org.acmemq&quot;,
      source-destination=&quot;sourceQ&quot;,
      source-connection-factory=&quot;ConnectionFactory&quot;,
      source-user=&quot;user1&quot;,
      source-password=&quot;pwd1&quot;,
      source-context={&quot;java.naming.factory.initial&quot; =&gt; &quot;org.acmemq.jndi.AcmeMQInitialContextFactory&quot;,
                      &quot;java.naming.provider.url&quot; =&gt; &quot;tcp://127.0.0.1:9292&quot;},
      target-destination=&quot;/jms/targetQ&quot;,
      target-connection-factory=&quot;/jms/invmTargetCF&quot;,
      quality-of-service=AT_MOST_ONCE,
      failure-retry-interval=500,
      max-retries=1,
      max-batch-size=500,
      max-batch-time=500,
      add-messageID-in-header=true)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also see the complete Jakarta Messaging Bridge resource description from the
CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging/jms-bridge=*/:read-resource-description
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [{
        &quot;address&quot; =&gt; [
            (&quot;subsystem&quot; =&gt; &quot;messaging&quot;),
            (&quot;jms-bridge&quot; =&gt; &quot;*&quot;)
        ],
        &quot;outcome&quot; =&gt; &quot;success&quot;,
        &quot;result&quot; =&gt; {
            &quot;description&quot; =&gt; &quot;A Jakarta Messaging bridge instance.&quot;,
            &quot;attributes&quot; =&gt; {
                ...
        }
    }]
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="Jakarta-Messaging-bridge-statistics"><a class="anchor" href="#Jakarta-Messaging-bridge-statistics"></a><a class="link" href="#Jakarta-Messaging-bridge-statistics">Statistics of a Jakarta Messaging Bridge</a></h5>
<div class="paragraph">
<p>Currently two statistics are available on a Jakarta Messaging bridge: the number of processed messages and the number of aborted/rolled back messages.
Those are available with the following command :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ruby"><span class="regexp"><span class="delimiter">/</span><span class="content">subsystem=messaging</span><span class="delimiter">/</span></span>jms-bridge=<span class="key">myBridge</span>:read-attribute(name=message-count)
{
    <span class="string"><span class="delimiter">&quot;</span><span class="content">outcome</span><span class="delimiter">&quot;</span></span> =&gt; <span class="string"><span class="delimiter">&quot;</span><span class="content">success</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span> =&gt; <span class="integer">0</span><span class="constant">L</span>
}

<span class="regexp"><span class="delimiter">/</span><span class="content">subsystem=messaging</span><span class="delimiter">/</span></span>jms-bridge=<span class="key">myBridge</span>:read-attribute(name=aborted-message-count)
{
    <span class="string"><span class="delimiter">&quot;</span><span class="content">outcome</span><span class="delimiter">&quot;</span></span> =&gt; <span class="string"><span class="delimiter">&quot;</span><span class="content">success</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span> =&gt; <span class="integer">0</span><span class="constant">L</span>
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="component-reference"><a class="anchor" href="#component-reference"></a><a class="link" href="#component-reference">7.8.11. Component Reference</a></h4>
<div class="paragraph">
<p>The messaging-activemq subsystem is provided by the Artemis project. For
a detailed description of the available configuration properties, please
consult the project documentation.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>Artemis Homepage: <a href="http://activemq.apache.org/artemis/" class="bare">http://activemq.apache.org/artemis/</a></p>
</li>
<li>
<p>Artemis User Documentation:
<a href="http://activemq.apache.org/artemis/docs.html" class="bare">http://activemq.apache.org/artemis/docs.html</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect4">
<h5 id="controlling-internal-broker-usage-of-memory-and-disk-space"><a class="anchor" href="#controlling-internal-broker-usage-of-memory-and-disk-space"></a><a class="link" href="#controlling-internal-broker-usage-of-memory-and-disk-space">Controlling internal broker usage of memory and disk space</a></h5>
<div class="paragraph">
<p>You can configure the disk space usage of the journal by using the <code>global-max-disk-usage</code> attribute, thus blocking the paging and processing of new messages until some disk space is available.
This is done from the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:write-attribute(name=global-max-disk-usage, value=70)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can define at which frequency the disk usage is checked using the <code>disk-scan-period</code> attribute.</p>
</div>
<div class="paragraph">
<p>In the same way configure the maximal memory affected to processing messages by using the <code>global-max-memory-size</code> attribute, thus blocking the processing of new messages until some memory space is available.
This is done from the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:write-attribute(name=global-max-memory-size, value=960000000)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="critical-analysis-of-the-broker"><a class="anchor" href="#critical-analysis-of-the-broker"></a><a class="link" href="#critical-analysis-of-the-broker">Critical analysis of the broker</a></h5>
<div class="paragraph">
<p>When things go wrong on the broker, the critical analyzer may act as a safeguard shutting down the broker or the JVM.<br>
If the response time goes beyond a configured timeout, the broker is considered unstable and an action can be taken to either shutdown the broker or halt the VM.
Currently in WildFly this will only be logged but you can change that behaviour by setting the <code>critical-analyzer-policy</code> attribute to <strong>HALT</strong> or <strong>SHUTDOWN</strong>.
For this, the critical analyzer measures the response time in:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Queue delivery (adding to the queue)</p>
</li>
<li>
<p>Journal storage</p>
</li>
<li>
<p>Paging operations</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can configure the critical analyzer on the broker using the CLI.
To disable the critical analyzer, you can execute the following CLI command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:write-attribute(name=critical-analyzer-enabled, value=false)
{
    "outcome" =&gt; "success",
    "response-headers" =&gt; {
        "operation-requires-reload" =&gt; true,
        "process-state" =&gt; "reload-required"
    }
}</pre>
</div>
</div>
<div class="paragraph">
<p>You can configure the critical analyzer with the following attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>critical-analyzer-enabled</p>
</li>
<li>
<p>critical-analyzer-timeout</p>
</li>
<li>
<p>critical-analyzer-check-period</p>
</li>
<li>
<p>critical-analyzer-policy</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="importing-exporting-the-journal"><a class="anchor" href="#importing-exporting-the-journal"></a><a class="link" href="#importing-exporting-the-journal">Importing / Exporting the Journal</a></h5>
<div class="paragraph">
<p>WildFly provides an operation to <code>export</code> the journal to a file which <strong>MUST</strong> be run in <code>admin-mode</code>.
This is done from the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:export-journal()
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;$JBOSS_HOME/standalone/data/activemq/journal-20210125-103331692+0100-dump.xml&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can now import such a dump file, in <code>normal</code> mode, using the command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:import-journal(file=$FILE_PATH/journal-20210125-103331692+0100-dump.xml)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you need to troubleshoot the journal you can use the <code>print-data</code> operation. Like the <code>export</code> operation, it needs to be executed in <code>admin-mode</code>.
Also this will send back a file so it must be coupled with the <code>attachment</code> operation to display or save the result. Note that the <code>display</code> operation won&#8217;t work properly if you are asking for a zipped version of the data.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] attachment display --operation=/subsystem=messaging-activemq/server=default:print-data(secret)
ATTACHMENT a69b87f3-ffeb-4596-be51-d73ebdc48b66:
     _        _               _
    / \  ____| |_  ___ __  __(_) _____
   / _ \|  _ \ __|/ _ \  \/  | |/  __/
  / ___ \ | \/ |_/  __/ |\/| | |\___ \
 /_/   \_\|   \__\____|_|  |_|_|/___ /
 Apache ActiveMQ Artemis 2.16.0

 ....</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Messaging_Connect_a_pooled-connection-factory_to_a_Remote_Artemis_Server"><a class="anchor" href="#Messaging_Connect_a_pooled-connection-factory_to_a_Remote_Artemis_Server"></a><a class="link" href="#Messaging_Connect_a_pooled-connection-factory_to_a_Remote_Artemis_Server">7.8.12. Connect a pooled-connection-factory to a Remote Artemis Server</a></h4>
<div class="paragraph">
<p>The <code>messaging-activemq</code> subsystem allows to configure a
<code>pooled-connection-factory</code> resource to let a local client deployed in
WildFly connect to a remote Artemis server.</p>
</div>
<div class="paragraph">
<p>The configuration of such a <code>pooled-connection-factory</code> is done in 3
steps:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>create an outbound-socket-binding pointing to the remote messaging
server:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-artemis:add(host=&lt;server host&gt;, port=61616)</code></pre>
</div>
</div>
</li>
<li>
<p>create a remote-connector referencing the outbound-socket-binding
created at step (1).</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/remote-connector=remote-artemis:add(socket-binding=remote-artemis)</code></pre>
</div>
</div>
</li>
<li>
<p>create a pooled-connection-factory referencing the remote-connector
created at step (2).</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/pooled-connection-factory=remote-artemis:add(connectors=[remote-artemis], entries=[java:/jms/remoteCF])</code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>In Artemis 1.x topics and queues used had a prefix(jms.topic. and jms.queue.) that were prepended to the destination name.
In Artemis 2.x this is no longer the case, but for compatibility reasons WildFly still prepend those prefixes and tells Artemis to run in compatibility mode.
If you  are connecting to a remote Artemis 2.x, it may not be in compatibility mode and thus the old prefixes may not be used anymore.
If you need to use destinations without those prefixes, you can configure your connection factory not to use them by setting the attribute <code>enable-amq1-prefix</code> to false.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/pooled-connection-factory=remote-artemis:write-attribute(name=&quot;enable-amq1-prefix&quot;, value=&quot;false&quot;)</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="jakarta_messaging_queues_topics_on_remote_artemis_server"><a class="anchor" href="#jakarta_messaging_queues_topics_on_remote_artemis_server"></a><a class="link" href="#jakarta_messaging_queues_topics_on_remote_artemis_server">Jakarta Messaging Queues and Topics on a remote Artemis Server</a></h5>
<div class="paragraph">
<p>You can also add queues and topics defined on a remote Artemis server to be used as if they were local to the server. This means that you can make those remote destinations available via JNDI just like local destinations.
You can also configure destinations not to enable the Artemis 1.x prefixes by setting the attribute <code>enable-amq1-prefix</code> to false. Those destinations are defined out-of the server element:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;external-jms-queue</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testQueue</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms/queue/test java:jboss/exported/jms/queue/test</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">enable-amq1-prefix</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;external-jms-topic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testTopic</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jms/topic/test java:jboss/exported/jms/topic/test</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">enable-amq1-prefix</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Jakarta Messaging endpoints can easily be created through the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ruby">[standalone<span class="instance-variable">@localhost</span>:<span class="integer">9990</span> /] /subsystem=messaging-activemq/external-jms-queue=<span class="key">myQueue</span>:read-resource
{
    <span class="string"><span class="delimiter">&quot;</span><span class="content">outcome</span><span class="delimiter">&quot;</span></span> =&gt; <span class="string"><span class="delimiter">&quot;</span><span class="content">success</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span> =&gt; {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">entries</span><span class="delimiter">&quot;</span></span> =&gt; [<span class="string"><span class="delimiter">&quot;</span><span class="content">queues/myQueue</span><span class="delimiter">&quot;</span></span>]
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You don&#8217;t have operations to see or manage attributes of those destinations.</p>
</div>
</div>
<div class="sect4">
<h5 id="configuration-of-a-mdb-using-a-pooled-connection-factory"><a class="anchor" href="#configuration-of-a-mdb-using-a-pooled-connection-factory"></a><a class="link" href="#configuration-of-a-mdb-using-a-pooled-connection-factory">Configuration of a MDB using a pooled-connection-factory</a></h5>
<div class="paragraph">
<p>When a <code>pooled-connection-factory</code> is configured to connect to a remote
Artemis, it is possible to configure Message-Driven Beans (MDB) to have
them consume messages from this remote server.</p>
</div>
<div class="paragraph">
<p>The MDB must be annotated with the <code>@ResourceAdapter</code> annotation using
the <strong>name</strong> of the <code>pooled-connection-factory resource</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.jboss.ejb3.annotation.ResourceAdapter</span>;
<span class="error"> </span>
  <span class="annotation">@ResourceAdapter</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">remote-artemis</span><span class="delimiter">&quot;</span></span>)
  <span class="annotation">@MessageDriven</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">MyMDB</span><span class="delimiter">&quot;</span></span>, activationConfig = {
    ...
})
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyMDB</span> <span class="directive">implements</span> MessageListener {
      <span class="directive">public</span> <span class="type">void</span> onMessage(Message message) {
       ...
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the MDB needs to produce messages to the remote server, it must
inject the <code>pooled-connection-factory</code> by looking it up in JNDI using
one of its <code>entries</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Inject</span>
<span class="annotation">@JMSConnectionFactory</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">java:/jms/remoteCF</span><span class="delimiter">&quot;</span></span>)
<span class="directive">private</span> JMSContext context;</code></pre>
</div>
</div>
<div class="sect5">
<h6 id="configuration-of-the-destination"><a class="anchor" href="#configuration-of-the-destination"></a><a class="link" href="#configuration-of-the-destination">Configuration of the destination</a></h6>
<div class="paragraph">
<p>A MDB must also specify which destination it will consume messages from.</p>
</div>
<div class="paragraph">
<p>The standard way is to define a <code>destinationLookup</code> activation config
property that corresponds to a JNDI lookup on the local server.<br>
When the MDB is consuming from a remote Artemis server it will now create those bindings locally.<br>
It is possible to use the naming subsystem to configure
<a href="#Naming">external context federation</a> to have local JNDI
bindings delegating to external bindings.</p>
</div>
<div class="paragraph">
<p>However there is a simpler solution to configure the destination when
using the Artemis Resource Adapter.<br>
Instead of using JDNI to lookup the Jakarta Messaging Destination resource, you can
just specify the <strong>name</strong> of the destination (as configured in the remote
Artemis server) using the <code>destination</code> activation config property and
set the <code>useJNDI</code> activation config property to false to let the Artemis
Resource Adapter create automatically the Jakarta Messaging destination without
requiring any JNDI lookup.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@ResourceAdapter</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">remote-artemis</span><span class="delimiter">&quot;</span></span>)
<span class="annotation">@MessageDriven</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">MyMDB</span><span class="delimiter">&quot;</span></span>, activationConfig = {
    <span class="annotation">@ActivationConfigProperty</span>(propertyName = <span class="string"><span class="delimiter">&quot;</span><span class="content">useJNDI</span><span class="delimiter">&quot;</span></span>,         propertyValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span>),
    <span class="annotation">@ActivationConfigProperty</span>(propertyName = <span class="string"><span class="delimiter">&quot;</span><span class="content">destination</span><span class="delimiter">&quot;</span></span>,     propertyValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">myQueue</span><span class="delimiter">&quot;</span></span>),
    <span class="annotation">@ActivationConfigProperty</span>(propertyName = <span class="string"><span class="delimiter">&quot;</span><span class="content">destinationType</span><span class="delimiter">&quot;</span></span>, propertyValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">jakarta.jms.Queue</span><span class="delimiter">&quot;</span></span>),<span class="error"> </span>
    <span class="annotation">@ActivationConfigProperty</span>(propertyName = <span class="string"><span class="delimiter">&quot;</span><span class="content">acknowledgeMode</span><span class="delimiter">&quot;</span></span>, propertyValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">Auto-acknowledge</span><span class="delimiter">&quot;</span></span>)
})
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyMDB</span> <span class="directive">implements</span> MessageListener {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>These properties configure the MDB to consume messages from the Jakarta Messaging
Queue named <code>myQueue</code> hosted on the remote Artemis server.<br>
In most cases, such a MDB does not need to lookup other destinations to
process the consumed messages and it can use the JMSReplyTo destination
if it is defined on the message.<br>
If the MDB needs any other Jakarta Messaging destinations defined on the remote
server, it must use client-side JNDI by following the
<a href="http://http://activemq.apache.org/artemis/docs/2.6.0/using-jms.html#jndi-configuration">Artemis
documentation</a> or configure external configuration context in the naming
subsystem (which allows to inject the Jakarta Messaging resources using the
<code>@Resource</code> annotation).</p>
</div>
</div>
<div class="sect5">
<h6 id="configuration-of-a-remote-destination-using-annotations"><a class="anchor" href="#configuration-of-a-remote-destination-using-annotations"></a><a class="link" href="#configuration-of-a-remote-destination-using-annotations">Configuration of a remote destination using annotations</a></h6>
<div class="paragraph">
<p>The annotation <code>@JMSDestinationDefinition</code> can be used to create a destination on a remote Artemis Server. This will work in the same way as for a local server.
For this it needs to be able to access Artemis management queue. If your remote Artemis Server management queue is not the default one you can pass the management queue address as a property to the <code>@JMSDestinationDefinition</code>.
Please note that the destination is created remotely but won&#8217;t be removed once the deployement is undeployed/removed.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@JMSDestinationDefinition</span>(
    <span class="comment">// explicitly mention a resourceAdapter corresponding to a pooled-connection-factory resource to the remote server</span>
    resourceAdapter = <span class="string"><span class="delimiter">&quot;</span><span class="content">activemq-ra</span><span class="delimiter">&quot;</span></span>,
    name=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/env/myQueue2</span><span class="delimiter">&quot;</span></span>,
    interfaceName=<span class="string"><span class="delimiter">&quot;</span><span class="content">jakarta.jms.Queue</span><span class="delimiter">&quot;</span></span>,
    destinationName=<span class="string"><span class="delimiter">&quot;</span><span class="content">myQueue2</span><span class="delimiter">&quot;</span></span>,
        properties = {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">management-address=my.management.queue</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">selector=color = 'red'</span><span class="delimiter">&quot;</span></span>
       }
)</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also configure destinations not to enable the Artemis 1.x prefixes by adding a property <code>enable-amq1-prefix</code> to false to the <code>@JMSDestinationDefinition</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@JMSDestinationDefinition</span>(
    <span class="comment">// explicitly mention a resourceAdapter corresponding to a pooled-connection-factory resource to the remote server</span>
    resourceAdapter = <span class="string"><span class="delimiter">&quot;</span><span class="content">activemq-ra</span><span class="delimiter">&quot;</span></span>,
    name=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:global/env/myQueue2</span><span class="delimiter">&quot;</span></span>,
    interfaceName=<span class="string"><span class="delimiter">&quot;</span><span class="content">jakarta.jms.Queue</span><span class="delimiter">&quot;</span></span>,
    destinationName=<span class="string"><span class="delimiter">&quot;</span><span class="content">myQueue2</span><span class="delimiter">&quot;</span></span>,
    properties = {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">enable-amq1-prefix=false</span><span class="delimiter">&quot;</span></span>
    }
)</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Messaging_Backward_and_Forward_Compatibility"><a class="anchor" href="#Messaging_Backward_and_Forward_Compatibility"></a><a class="link" href="#Messaging_Backward_and_Forward_Compatibility">7.8.13. Backward &amp; Forward Compatibility</a></h4>
<div class="paragraph">
<p>WildFly supports both backwards and forwards compatibility with
legacy versions that were using HornetQ as their messaging brokers (such
as JBoss AS7 or WildFly 8 and 9).<br>
These two compatibility modes are provided by the ActiveMQ Artemis
project that supports HornetQ&#8217;s CORE protocol:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>backward compatibility: WildFly messaging clients (using Artemis) can
connect to a legacy app server (running HornetQ)</p>
</li>
<li>
<p>forward compatibility: legacy messaging clients (using HornetQ) can connect
to a WildFly 27 app server (running Artemis).</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="forward-compatibility"><a class="anchor" href="#forward-compatibility"></a><a class="link" href="#forward-compatibility">Forward Compatibility</a></h5>
<div class="paragraph">
<p>Forward compatibility requires no code change in legacy messaging clients. It
is provided by the WildFly messaging-activemq subsystem and its
resources.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>legacy-connection-factory</code> is a subresource of the
<code>messaging-activemq&#8217;s `server</code> and can be used to store in JNDI a
HornetQ-based ConnectionFactory.</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:messaging-activemq:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span> 
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        ...
        <span class="tag">&lt;legacy-connection-factory</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">legacyConnectionFactory-discovery</span><span class="delimiter">&quot;</span></span><span class="error"> </span>
                                   <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/RemoteConnectionFactory</span><span class="delimiter">&quot;</span></span>
                                   <span class="attribute-name">...</span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/server&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Legacy HornetQ-based messaging destinations can also be configured by
providing a <code>legacy-entries</code> attribute to the <code>jms-queue</code> and
<code>jms-topic</code> resource.</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">    <span class="tag">&lt;jms-queue</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">myQueue</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/myQueue-new</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">legacy-entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/myQueue</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;jms-topic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testTopic</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/myTopic-new</span><span class="delimiter">&quot;</span></span>
               <span class="attribute-name">legacy-entries</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/exported/jms/myTopic</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>legacy-entries</code> must be used by legacy clients (using HornetQ)
while the regular <code>entries</code> are for WildFly 27 Jakarta Messaging clients (using
Artemis).</p>
</div>
<div class="paragraph">
<p>The legacy client will then lookup these <code>legacy</code> messaging resources to
communicate with WildFly.<br>
To avoid any code change in the legacy messaging clients, the legacy JNDI
entries must match the lookup expected by the legacy client.</p>
</div>
<div class="sect5">
<h6 id="migration"><a class="anchor" href="#migration"></a><a class="link" href="#migration">Migration</a></h6>
<div class="paragraph">
<p>During migration, the legacy <code>messaging</code> subsystem will create a
<code>legacy-connection-factory</code> resource and add <code>legacy-entries</code> to the
<code>jms-queue</code> and <code>jms-topic</code> resource if the boolean attribute
<code>add-legacy-entries</code> is set to <code>true</code> for its <code>migrate</code> operation. If
that is the case, the legacy entries in the migrated
<code>messaging-activemq</code> subsystem will correspond to the entries specified
in the legacy <code>messaging</code> subsystem and the regular entries will be
created with a <code>-new</code> suffix.<br>
If <code>add-legacy-entries</code> is set to <code>false</code> during migration, no legacy
resources will be created in the <code>messaging-activemq</code> subsystem and
legacy messaging clients will not be able to communicate with WildFly 27
servers.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="backward-compatibility"><a class="anchor" href="#backward-compatibility"></a><a class="link" href="#backward-compatibility">Backward Compatibility</a></h5>
<div class="paragraph">
<p>Backward compatibility requires no configuration change in the legacy
server.<br>
WildFly 27 clients do not look up resources on the legacy server but
use client-side JNDI to create their Jakarta Messaging resources. WildFly&#8217;s Artemis client
can then use these resources to communicate with the legacy server
using the HornetQ CORE protocol.</p>
</div>
<div class="paragraph">
<p>Artemis supports
<a href="http://activemq.apache.org/artemis/docs/1.1.0/using-jms.html#jndi-configuration">Client-side
JNDI</a> to create Jakarta Messaging resources ( <code>ConnectionFactory</code> and <code>Destination</code>).</p>
</div>
<div class="paragraph">
<p>For example, if a WildFly 27 messaging client wants to communicate with a
legacy server using a queue named <code>myQueue</code>, it must use the
following properties to configure its JNDI <code>InitialContext</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.jms/ConnectionFactory=tcp://&lt;legacy server address&gt;:5445? \
    protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
queue.jms/myQueue=myQueue</code></pre>
</div>
</div>
<div class="paragraph">
<p>It can then use the <code>jms/ConnectionFactory</code> name to create the Jakarta Messaging
ConnectionFactory and <code>jms/myQueue</code> to create the Jakarta Messaging Queue.<br>
Note that the property
<code>protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory</code>
is mandatory when specifying the URL of the legacy connection factory so
that the Artemis JMS client can communicate with the HornetQ broker in
the legacy server.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Mesaging_AIO_-_NIO_for_messaging_journal"><a class="anchor" href="#Mesaging_AIO_-_NIO_for_messaging_journal"></a><a class="link" href="#Mesaging_AIO_-_NIO_for_messaging_journal">7.8.14. AIO - NIO for messaging journal</a></h4>
<div class="paragraph">
<p>Apache ActiveMQ Artemis (like HornetQ beforehand) ships with a <strong>high
performance journal</strong>. Since Apache ActiveMQ Artemis handles its own
persistence, rather than relying on a database or other 3rd party
persistence engine it is very highly optimised for the specific
messaging use cases. The majority of the journal is written in Java,
however we abstract out the interaction with the actual file system to
allow different pluggable implementations.</p>
</div>
<div class="paragraph">
<p>Apache ActiveMQ Artemis ships with two implementations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Java NIO.</strong></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The first implementation uses standard Java NIO to interface with the
file system. This provides extremely good performance and runs on any
platform where there&#8217;s a Java 6+ runtime.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Linux Asynchronous IO</strong></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The second implementation uses a thin native code wrapper to talk to the
Linux asynchronous IO library (AIO). With AIO, Apache ActiveMQ Artemis
will be called back when the data has made it to disk, allowing us to
avoid explicit syncs altogether and simply send back confirmation of
completion when AIO informs us that the data has been persisted.</p>
</div>
<div class="paragraph">
<p>Using AIO will typically provide even better performance than using Java
NIO.</p>
</div>
<div class="paragraph">
<p>The AIO journal is only available when running Linux kernel 2.6 or later
and after having installed libaio (if it&#8217;s not already installed). If AIO is
not supported on the system then Artemis will fallback to NIO. To know which
type of journal is effectively used you can execute the following command using jboss-cli:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/server=default:read-attribute(name=runtime-journal-type)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Please note that AIO is represented by ASYNCIO in the WildFly model configuration.</p>
</div>
<div class="paragraph">
<p>Also, please note that AIO will only work with the following file
systems: ext2, ext3, ext4, jfs, xfs. With other file systems, e.g. NFS
it may appear to work, but it will fall back to a slower synchronous
behaviour. Don&#8217;t put the journal on a NFS share!</p>
</div>
<div class="paragraph">
<p><strong>One point that should be added is that AIO doesn&#8217;t work well with
encrypted partitions, thus you have to move to NIO on those.</strong></p>
</div>
<div class="paragraph">
<p>What are the symptoms of an AIO isssue ?</p>
</div>
<div class="sect4">
<h5 id="aio-issue-on-wildfly-10"><a class="anchor" href="#aio-issue-on-wildfly-10"></a><a class="link" href="#aio-issue-on-wildfly-10">AIO issue on WildFly 10</a></h5>
<div class="paragraph">
<p>If you see the following exception in your WildFly log file / console</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 64) AMQ222010: Critical IO Error, shutting down the server. file=AIOSequentialFile:/home/wildfly/wildfly-10.0.0.Final/standalone/data/activemq/journal/activemq-data-2.amq, message=Cannot open file:The Argument is invalid: java.io.IOException: Cannot open file:The Argument is invalid
 at org.apache.activemq.artemis.jlibaio.LibaioContext.open(Native Method)</pre>
</div>
</div>
<div class="paragraph">
<p>that means that AIO isn&#8217;t working properly on your system.</p>
</div>
<div class="paragraph">
<p>To use NIO instead execute the following command using jboss-cli:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/server=default:write-attribute(name=journal-type, value=NIO)</code></pre>
</div>
</div>
<div class="paragraph">
<p>You need to reload or restart your server and you should see the
following trace in your server console :</p>
</div>
<div class="literalblock">
<div class="content">
<pre>INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 64) AMQ221013: Using NIO Journal</pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="aio-issue-on-wildfly-9"><a class="anchor" href="#aio-issue-on-wildfly-9"></a><a class="link" href="#aio-issue-on-wildfly-9">AIO issue on WildFly 9</a></h5>
<div class="literalblock">
<div class="content">
<pre>[org.hornetq.core.server] (ServerService Thread Pool -- 64) HQ222010: Critical IO Error, shutting down the server. file=AIOSequentialFile:/home/wildfly/wildfly-9.0.2.Final/standalone/data/messagingjournal/hornetq-data-1.hq, message=Can't open file: HornetQException[errorType=NATIVE_ERROR_CANT_OPEN_CLOSE_FILE message=Can't open file]
 at org.hornetq.core.libaio.Native.init(Native Method)</pre>
</div>
</div>
<div class="paragraph">
<p>that means that AIO isn&#8217;t working properly on your system.</p>
</div>
<div class="paragraph">
<p>To use NIO instead execute the following commnd using jboss-cli :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging/hornetq-server=default:write-attribute(name=journal-type,value=NIO)</code></pre>
</div>
</div>
<div class="paragraph">
<p>You need to reload or restart your server and you see the following
trace in your server console :</p>
</div>
<div class="literalblock">
<div class="content">
<pre>INFO  [org.hornetq.core.server] (ServerService Thread Pool -- 64) HQ221013: Using NIO Journal</pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Messaging_JDBC_Store_for_Messaging_Journal"><a class="anchor" href="#Messaging_JDBC_Store_for_Messaging_Journal"></a><a class="link" href="#Messaging_JDBC_Store_for_Messaging_Journal">7.8.15. JDBC Store for Messaging Journal</a></h4>
<div class="paragraph">
<p>The Artemis server that are integrated to WildFly can be configured to
use a JDBC store for its messaging journal instead of its file-based
journal.<br>
The <code>server resource</code> of the messaging-activemq subsystem needs to
configure its <code>journal-datasource</code> attribute to be able to use JDBC
store. If this attribute is not defined, the regular file-base journal
will be used for the Artemis server.<br>
This attribute value must correspond to a data source defined in the
datasource subsystem.</p>
</div>
<div class="paragraph">
<p>For example, if the datasources subsystem defines an <code>ExampleDS</code> data
source at <code>/subsystem=datasources/data-source=ExampleDS</code>, the Artemis
server can use it for its JDBC store with the operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/server=default:write-attribute(name=journal-datasource, value=ExampleDS)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Artemis JDBC store uses SQL commands to create the tables used to
persist its information.<br>
These SQL commands may differ depending on the type of database. The SQL
commands used by the JDBC store are located in <code>modules/system/layers/base/org/apache/activemq/artemis/main/artemis-jdbc-store-${ARTEMIS_VERSION}.jar/journal-sql.properties</code>.</p>
</div>
<div class="paragraph">
<p>Artemis uses different JDBC tables to store its bindings information,
the persistent messages and the large messages (paging is not supported
yet).</p>
</div>
<div class="paragraph">
<p>The name of these tables can be configured with the
<code>journal-bindings-table</code>, <code>journal-messages-table</code>,
<code>journal-page-store-table, and journal-large-messages-table</code>.</p>
</div>
<div class="paragraph">
<p>Please note that the configuration of the underlying pool is something that you need to take care of.
You  need at least four connections:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>one for the binding</p>
</li>
<li>
<p>one for the messages journal</p>
</li>
<li>
<p>one for the lease lock (if you use HA)</p>
</li>
<li>
<p>one for the node manager shared state (if you use HA)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>So you should define a <a href="wildscribe/subsystem/datasources/xa-data-source/index.html#attr-min-pool-size"><code>min-pool-size</code></a> of 4 for the pool.<br>
But one fact that you need to take into account is that paging and large messages can use an unbounded number of threads.
The size, a.k.a. <a href="wildscribe/subsystem/datasources/xa-data-source/index.html#attr-max-pool-size"><code>max-pool-size</code></a>, of the pool should be defined according to the amount of concurrent threads that perform page/large message streaming operations. There is no defined rule for this as there is no 1-1 relation between the number of threads and the number of connections. The number of connections depend on the number of threads processing paging and large messages operations as well as the time you are willing to wait to get a connection (cf. <a href="https://docs.wildfly.org/22/wildscribe/subsystem/datasources/xa-data-source/index.html#attr-blocking-timeout-wait-millis"><code>blocking-timeout-wait-millis</code></a>). When new large messages or paging operations occur they will be in a dedicated thread and will try to get a connection, being enqueued until one is ready or the time to obtain one runs out which will create a failure.<br>
You really need to tailor your configuration according to your needs and test it in your environment following the <a href="#DataSource">DataSource configuration</a> subsystem documentation and perform tests and peroformance runs before going to production.</p>
</div>
<div class="sect4">
<h5 id="reference"><a class="anchor" href="#reference"></a><a class="link" href="#reference">Reference</a></h5>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>Artemis JDBC Persistence -
<a href="https://activemq.apache.org/components/artemis/documentation/latest/persistence.html#configuring-jdbc-persistence" class="bare">https://activemq.apache.org/components/artemis/documentation/latest/persistence.html#configuring-jdbc-persistence</a></p>
</li>
<li>
<p>WildFly DataSource subsystem documentation -
<a href="#DataSource">DataSource configuration</a></p>
</li>
<li>
<p>WildFly datasource configuration model
link:wildscribe/subsystem/datasources/xa-data-source/index.html</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Messaging_Discovery_Configuration"><a class="anchor" href="#Messaging_Discovery_Configuration"></a><a class="link" href="#Messaging_Discovery_Configuration">7.8.16. Configuring Broadcast/Discovery</a></h4>
<div class="paragraph">
<p>Each Artemis server can be configured to broadcast itself and/or discovery other Artemis servers within a cluster.
Artemis supports two mechanisms for configuring broadcast/discovery:</p>
</div>
<div class="sect4">
<h5 id="jgroups-based-broadcastdiscovery"><a class="anchor" href="#jgroups-based-broadcastdiscovery"></a><a class="link" href="#jgroups-based-broadcastdiscovery">JGroups-based broadcast/discovery</a></h5>
<div class="paragraph">
<p>Artemis can leverage the membership of an existing JGroups channel to both broadcast its identity and discover nodes on which Artemis servers are deployed.
WildFly&#8217;s default full-ha profile uses this mechanism for broadcast/discovery using the default JGroups channel of the server (as defined by the JGroups subsystem).</p>
</div>
<div class="paragraph">
<p>To add this support to a profile that does not include it by default, use the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/broadcast-group=bg-group1:add(jgroups-cluster=activemq-cluster,connectors=http-connector)
[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/discovery-group=dg-group1:add(jgroups-cluster=activemq-cluster)</code></pre>
</div>
</div>
<div class="paragraph">
<p>To segregate Artemis servers use a distinct membership, configure broadcast/discovery using a separate channel.  To do this, first create the channel resource:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=jgroups/channel=messaging:add(stack=tcp)</code></pre>
</div>
</div>
<div class="paragraph">
<p>This creates a new JGroups channel resource based on the "tcp" protocol stack.
Now create your broadcast/discovery groups using this channel:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/broadcast-group=bg-group2:add(jgroups-channel=messaging, jgroups-cluster=activemq-cluster, connectors=http-connector)
[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/discovery-group=dg-group2:add(jgroups-channel=messaging, jgroups-cluster=activemq-cluster)</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="multicast-broadcastdiscovery"><a class="anchor" href="#multicast-broadcastdiscovery"></a><a class="link" href="#multicast-broadcastdiscovery">Multicast broadcast/discovery</a></h5>
<div class="paragraph">
<p>To broadcast identity to standalone messaging clients, you can additionally configure broadcast/discovery using multicast sockets.</p>
</div>
<div class="paragraph">
<p>e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /socket-binding-group=standard-sockets/socket-binding=messaging(interface=private, multicast-address=230.0.0.4, multicast-port=45689)

[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/broadcast-group=bg-group3:add(socket-binding=messaging, connectors=http-connector)
[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/discovery-group=dg-group3:add(socket-binding=messaging)</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="cluster-behind-an-http-load-balancer"><a class="anchor" href="#cluster-behind-an-http-load-balancer"></a><a class="link" href="#cluster-behind-an-http-load-balancer">Cluster behind an HTTP load balancer</a></h5>
<div class="paragraph">
<p>If the cluster is behind an HTTP load balancer we need to indicate to the clients that they must not use the cluster topology to connect to it but keep on using the initial connection to the load-balancer.
For this you need to specify on the (pooled) connection factory not to use the topology by setting the attribute "use-topology-for-load-balancing" to false.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=messaging-activemq/pooled-connection-factory=remote-artemis:write-attribute(name=&quot;use-topology-for-load-balancing&quot;, value=&quot;false&quot;)</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="network-isolation-split-brain"><a class="anchor" href="#network-isolation-split-brain"></a><a class="link" href="#network-isolation-split-brain">Network Isolation (Split Brain)</a></h5>
<div class="paragraph">
<p>It is possible that if a replicated live or backup server becomes isolated in a network that failover will occur and you will end up with 2 live servers serving messages in a cluster, this we call split brain. You main mitigate this problem by configuring one or more addresses that are part of your network topology, that will be pinged through the life cycle of the server.</p>
</div>
<div class="paragraph">
<p>The server will stop itself until the network is back on such case.
This is configured using the following configuration attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>network-check-NIC</code>: The NIC (Network Interface Controller) to be used to validate the network.</p>
</li>
<li>
<p><code>network-check-period</code>: The frequency of how often we should check if the network is still up.</p>
</li>
<li>
<p><code>network-check-timeout</code>: The timeout used on the ping.</p>
</li>
<li>
<p><code>network-check-list</code>: This is a comma separated list, no spaces, of DNS or IPs (it should accept IPV6) to be used to validate the network.</p>
</li>
<li>
<p><code>network-check-URL-list</code>: The list of HTTP URIs to be used to validate the network.</p>
</li>
<li>
<p><code>network-check-ping-command</code>: The command used to ping IPV4 addresses.</p>
</li>
<li>
<p><code>network-check-ping6-command</code>: The command used to ping IPV6 addresses.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, let&#8217;s ping the 10.0.0.1 IP address:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /]
/subsystem=messaging-activemq/server=default:write-attribute(name=network-check-list, value=&quot;10.0.0.1&quot;)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once 10.0.0.1 stops responding to the ping you will get an exception and the broker will stop:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>WARN  [org.apache.activemq.artemis.logs] (ServerService Thread Pool -- 84) AMQ202002: Ping Address /10.0.0.1 wasnt reacheable.
...
INFO  [org.apache.activemq.artemis.logs] (Network-Checker-0 (NetworkChecker)) AMQ201001: Network is unhealthy, stopping service ActiveMQServerImpl::serverUUID=76e64326-f78e-11ea-b7a5-3ce1a1c35439</code></pre>
</div>
</div>
<div class="sect5">
<h6 id="warning"><a class="anchor" href="#warning"></a><a class="link" href="#warning">Warning</a></h6>
<div class="paragraph">
<p>Make sure you understand your network topology as this is meant to validate your network. Using IPs that could eventually disappear or be partially visible may defeat the purpose. You can use a list of multiple IPs. Any successful ping will make the server OK to continue running</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Transactions_Subsystem"><a class="anchor" href="#Transactions_Subsystem"></a><a class="link" href="#Transactions_Subsystem">7.9. Transactions subsystem configuration</a></h3>
<div class="paragraph">
<p><strong>Required extension:</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.transactions</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Basic subsystem configuration example:</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  <span class="tag">&lt;core-environment</span> <span class="attribute-name">node-identifier</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.tx.node.id:1}</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;process-id&gt;</span>
      <span class="tag">&lt;uuid</span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/process-id&gt;</span>
  <span class="tag">&lt;/core-environment&gt;</span>
  <span class="tag">&lt;recovery-environment</span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-recovery-environment</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">status-socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-status-manager</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;coordinator-environment</span> <span class="attribute-name">statistics-enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${wildfly.transactions.statistics-enabled:${wildfly.statistics-enabled:false}}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  <span class="tag">&lt;object-store</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">tx-object-store</span><span class="delimiter">&quot;</span></span>
                <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.data.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect3">
<h4 id="transaction-subsystem-configuration"><a class="anchor" href="#transaction-subsystem-configuration"></a><a class="link" href="#transaction-subsystem-configuration">7.9.1. Transaction subsystem configuration</a></h4>
<div class="paragraph">
<p>Transaction subsystem configures the behaviour of the transaction manager.
<a href="https://narayana.io/">Narayana</a> is the transaction manager used in WildFly.
The second component configured within the subsystem is
<a href="https://github.com/wildfly/wildfly-transaction-client">WildFly Transaction Client</a>
(the WFTC serves as an abstract layer to work with the transactional context).</p>
</div>
<div class="sect4">
<h5 id="configuration-of-narayana-component"><a class="anchor" href="#configuration-of-narayana-component"></a><a class="link" href="#configuration-of-narayana-component">Configuration of Narayana component</a></h5>
<div class="paragraph">
<p>The structure of the transaction subsystem follows the structure of Narayana component.
Narayana defines a separate configuration bean for every
<a href="https://jbossts.blogspot.com/2018/01/narayana-periodic-recovery-of-xa.html#configuration">internal module</a>.
For example any configuration related to Narayana core is available through beans
<a href="https://github.com/jbosstm/narayana/blob/master.Final/ArjunaCore/arjuna/classes/com/arjuna/ats/arjuna/common/CoordinatorEnvironmentBean.java">CoordinatorEnvironmentBean</a> and
<a href="https://github.com/jbosstm/narayana/blob/master.Final/ArjunaCore/arjuna/classes/com/arjuna/ats/arjuna/common/CoreEnvironmentBean.java">CoreEnvironmentBean</a>,
for JTA processing it is
<a href="https://github.com/jbosstm/narayana/blob/master.Final/ArjunaJTA/jta/classes/com/arjuna/ats/jta/common/JTAEnvironmentBean.java">JTAEnvironmentBean</a>,
for the transaction recovery setup it&#8217;s
<a href="https://github.com/jbosstm/narayana/blob/master.Final/ArjunaCore/arjuna/classes/com/arjuna/ats/arjuna/common/RecoveryEnvironmentBean.java">RecoveryEnvironmentBean</a>.</p>
</div>
<div class="paragraph">
<p>The transaction subsystem provides only a sub-set of the configuration available via Narayana beans.
Any other configuration option provided by Narayana is still possible to be configured via
<a href="./#system-properties">system properties</a> and JVM restart is usually required.</p>
</div>
<div class="paragraph">
<p>Narayana defines unified naming for the system properties which are used for configuration.
The system property is in form <code>[bean name].[property name]</code>. For example, the system property with name
<a href="https://github.com/jbosstm/narayana/blob/master.Final/ArjunaCore/arjuna/classes/com/arjuna/ats/arjuna/common/RecoveryEnvironmentBean.java#L47"><code>RecoveryEnvironmentBean.periodicRecoveryInitilizationOffset</code></a>
configures a waiting time for first time execution of the periodic recovery after application server starts.</p>
</div>
</div>
<div class="sect4">
<h5 id="configuration-in-model-and-in-xml"><a class="anchor" href="#configuration-in-model-and-in-xml"></a><a class="link" href="#configuration-in-model-and-in-xml">Configuration in model and in XML</a></h5>
<div class="paragraph">
<p>The transaction subsystem separates the configuration into sections in XML configuration file.
Every section belongs to some Narayana module.
The configuration for model consists, on the other hand, of a flat structure of attributes
(most of them at top level).</p>
</div>
<div class="paragraph">
<p>For example, the subsystem defines the <code>node</code> identifier under <code>core-environment</code> XML element in XML
configuration, while the <code>node-identifer</code> attribute is defined directly under <code>/subsystem=transactions</code>
resource in the model.</p>
</div>
<div class="paragraph">
<p>The description of individual attributes and their meaning can be found in the
<a href="wildscribe{outfilesuffix/}subsystem/transactions">Model Reference Guide</a>.</p>
</div>
<div class="sect5">
<h6 id="jts"><a class="anchor" href="#jts"></a><a class="link" href="#jts">jts</a></h6>
<div class="paragraph">
<p><code>jts</code> model attribute is configured as <code>jts</code> XML element</p>
</div>
<div class="listingblock">
<div class="title">XML configuration enabling jts</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;jts</span> <span class="tag">/&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="core-environment"><a class="anchor" href="#core-environment"></a><a class="link" href="#core-environment">core-environment</a></h6>
<div class="paragraph">
<p><code>node-identifier</code>, <code>process-id-uuid</code>, <code>process-id-socket-binding</code>, <code>process-id-socket-max-ports</code> model
  attributes are configured under <code>core-environment</code> XML element</p>
</div>
<div class="listingblock">
<div class="title">XML configuration example for core-environment</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;core-environment</span> <span class="attribute-name">node-identifier</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;process-id&gt;</span>
      <span class="tag">&lt;socket</span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-socket-id</span><span class="delimiter">&quot;</span></span>
              <span class="attribute-name">socket-process-id-max-ports</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;/process-id&gt;</span>
  <span class="tag">&lt;/core-environment&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="recovery-environment"><a class="anchor" href="#recovery-environment"></a><a class="link" href="#recovery-environment">recovery-environment</a></h6>
<div class="paragraph">
<p><code>recovery-period</code>, <code>socket-binding</code>, <code>recovery-listener</code>, <code>status-socket-binding</code> model attributes are configured under <code>recovery-environment</code> XML element</p>
</div>
<div class="listingblock">
<div class="title">XML configuration example for recovery-environment</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;recovery-environment</span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-recovery-environment</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">status-socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">txn-status-manager</span><span class="delimiter">&quot;</span></span>
                        <span class="attribute-name">recovery-listener</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If you configure the <code>recovery-listener</code> then Narayana binds the linked socket, and a user may request
an explicit launch of
<a href="https://github.com/jbosstm/narayana/blob/master/ArjunaCore/arjuna/classes/com/arjuna/ats/arjuna/recovery/RecoveryDriver.java#L47">the recovery scan</a>.
We can see an example of the socket communication in the following example.</p>
</div>
<div class="listingblock">
<div class="title">telnet communication with recovery listener</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="bash">telnet localhost 4712
# command to start the recovery scan
SCAN[enter]
# at this time the transaction recovery has been started
^]
close</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="coordinator-environment"><a class="anchor" href="#coordinator-environment"></a><a class="link" href="#coordinator-environment">coordinator-environment</a></h6>
<div class="paragraph">
<p><code>enable-tsm-status</code>, <code>statistics-enabled</code>, <code>default-timeout</code>, <code>maximum-timeout</code>
model attributes are configured under <code>coordinator-environment</code> XML element</p>
</div>
<div class="listingblock">
<div class="title">XML configuration example for coordinator-environment</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;coordinator-environment</span> <span class="attribute-name">enable-tsm-status</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">statistics-enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>
                           <span class="attribute-name">default-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">300</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">maximum-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">31536000</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="sect6">
<h7 id="transaction-statistics"><a class="anchor" href="#transaction-statistics"></a><a class="link" href="#transaction-statistics">transaction statistics</a></h7>
<div class="paragraph">
<p>When subsystem defines the <code>statistics-enabled</code> to true Narayana starts gathering
statistics about transaction processing. User can view a single attribute
or list all statistics attributes as a group.
Transaction statistics attributes are read-only runtime attributes.</p>
</div>
<div class="listingblock">
<div class="title">observing all transaction statistics attributes</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="sh"># connect to a running application server
./bin/jboss-cli.sh -c

# enable transaction statistics
/subsystem=transactions:write-attribute(name=statistics-enabled, value=true)
# list all statistics attributes
/subsystem=transactions:read-attribute-group(name=statistics, include-runtime=true)</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="object-store"><a class="anchor" href="#object-store"></a><a class="link" href="#object-store">object-store</a></h5>
<div class="paragraph">
<p>Narayana needs to persist data about transaction processing to a transaction log.
This persistent storage is called object store in context of Narayana.
Narayana requires to persist a log for an XA transactions that are processed
with the two-phase commit protocol. Otherwise, the transaction is held only in memory
without storing anything to the object store.</p>
</div>
<div class="paragraph">
<p>Narayana provides three object stores implementations.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ShadowNoFileLock store persists records in directory structure on the file system.
A separate file represents an record, log of a prepared transaction.<br>
Used when attributes <code>use-jdbc-store</code> and <code>use-journal-store</code> are both <code>false</code>.</p>
</li>
<li>
<p>Journal store persists records in a journal file on the file system.
Records are stored in append only log implemented within <a href="https://github.com/apache/activemq-artemis/tree/main/artemis-journal">ActiveMQ Artemis</a>
project.<br>
Used when attribute <code>use-journal-store</code> is <code>true</code> and <code>use-jdbc-store</code> is <code>false</code>.</p>
</li>
<li>
<p>JDBC stores persists records in a database. The records are accessible via JDBC connection.
This store requires a linked <code>datasource</code> from the <code>datasources</code> subsystem.
Used when attribute <code>use-jdbc-store</code> is <code>true</code> and <code>use-journal-store</code> is <code>false</code>.</p>
</li>
</ul>
</div>
<div class="sect5">
<h6 id="journal-object-store"><a class="anchor" href="#journal-object-store"></a><a class="link" href="#journal-object-store">journal object-store</a></h6>
<div class="paragraph">
<p>An XML configuration of <code>object-store</code> XML element configuring the journal store with model attributes
<code>object-store-path</code>, <code>object-store-relative-to</code>, <code>journal-store-enable-async-io</code> is</p>
</div>
<div class="listingblock">
<div class="title">XML configuration example for object-store</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
    <span class="tag">&lt;object-store</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">tx-object-store</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.data.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;use-journal-store</span> <span class="attribute-name">enable-async-io</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="jdbc-object-store"><a class="anchor" href="#jdbc-object-store"></a><a class="link" href="#jdbc-object-store">JDBC object-store</a></h6>
<div class="paragraph">
<p>JDBC implementation makes the transaction log to be persisted into a database.
Transaction subsystem accesses the database via linked (via JNDI) non-transactional (<code>jta=false</code>) datasource.
When the transaction subsystem configures the JDBC store implementation then
the Transaction Manager creates one or few database tables (if they do not exist) to persist transaction data
when WildFly starts. Narayana creates a separate table for each store type.
Narayana uses the store type to grouping transaction records of the same type.</p>
</div>
<div class="paragraph">
<p>Narayana uses the following store types in WildFly</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>action store</em> stores data for JTA transactions</p>
</li>
<li>
<p><em>state store</em> stores data for TXOJ objects</p>
</li>
<li>
<p><em>communications store</em> stores data for monitoring remote JTS transactions and storing CORBA IOR&#8217;s</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Attributes configuration may define a prefix for each store type.
When we configure no prefix, or the same prefix for all store types
then Narayana saves the transaction data into the same database table.
By default, Narayana persists transaction log in database table named <code>JBossTSTxTable</code>.</p>
</div>
<div class="listingblock">
<div class="title">jboss cli example to setup JDBC object store</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="sh"># PostgreSQL driver module
./bin/jboss-cli.sh &quot;embed-server, module add --name=org.postgresql --resources=/tmp/postgresql.jar \
  --dependencies=javax.api\,jakarta.transaction.api&quot;

# non-jta PostgreSQL datasource creation
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml,data-source add --name=JDBCStore \
  --jndi-name=java:jboss/datasources/jdbcstore_postgresql --jta=false \
  --connection-url=jdbc:postgresql://localhost:5432/test --user-name=test --password=test \
  --driver-name=postgresql&quot;

# transaction subsystem configuration
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml, \
  /subsystem=transactions:write-attribute(name=jdbc-store-datasource, \
  value=java:jboss/datasources/jdbcstore_postgresql), \
  /subsystem=transactions:write-attribute(name=use-jdbc-store,value=true)&quot;
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml, \
  /subsystem=transactions:write-attribute(name=jdbc-state-store-table-prefix,value=state), \
  /subsystem=transactions:write-attribute(name=jdbc-state-store-drop-table,value=false),
  /subsystem=transactions:write-attribute(name=jdbc-communication-store-table-prefix,value=communication), \
  /subsystem=transactions:write-attribute(name=jdbc-communication-store-drop-table,value=false),
  /subsystem=transactions:write-attribute(name=jdbc-action-store-table-prefix,value=action), \
  /subsystem=transactions:write-attribute(name=jdbc-action-store-drop-table,value=false)&quot;</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">XML configuration example for JDBC object-store</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
    <span class="tag">&lt;jdbc-store</span> <span class="attribute-name">datasource-jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/jdbcstore_postgresql</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;action</span> <span class="attribute-name">table-prefix</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">action</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">drop-table</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;communication</span> <span class="attribute-name">table-prefix</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">communication</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">drop-table</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;state</span> <span class="attribute-name">table-prefix</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">drop-table</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/jdbc-store&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="commit-markable-resources"><a class="anchor" href="#commit-markable-resources"></a><a class="link" href="#commit-markable-resources">commit-markable-resources</a></h5>
<div class="paragraph">
<p>Makes possible for a database non-XA datasource (i.e., a local resource) to reliably
participate in an XA transaction
in the <a href="http://jbossts.blogspot.com/2018/06/narayana-commit-markable-resource.html">two-phase commit</a> processing.
The datasource has to be configured with <code>connectable</code> attribute of value <code>true</code> and linked to transaction
subsystem as a commit markable resource (CMR).</p>
</div>
<div class="paragraph">
<p>As a prerequisite the database <strong>must</strong> contain a table named <code>xids</code>
(the database table name can be configured with attribute name under commit-markable-resource)
where Narayana persists additional metadata when <em>two-phase commit</em> prepares the non-XA datasource.</p>
</div>
<div class="paragraph">
<p>The SQL select that has to be working for <code>xids</code> table can be found
<a href="https://github.com/jbosstm/narayana/blob/master/ArjunaJTA/jta/classes/com/arjuna/ats/internal/jta/recovery/arjunacore/CommitMarkableResourceRecordRecoveryModule.java">in the Narayana code</a>.</p>
</div>
<div class="listingblock">
<div class="title">example of SQL statement to create the <code>xids</code> table to store CMR metadata</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="sql"><span class="comment">-- PostgreSQL</span>
<span class="class">CREATE</span> <span class="type">TABLE</span> xids (
  xid bytea, transactionManagerID <span class="predefined-type">varchar</span>(<span class="integer">64</span>), actionuid bytea
);
<span class="class">CREATE</span> <span class="directive">UNIQUE</span> <span class="type">INDEX</span> index_xid <span class="keyword">ON</span> xids (xid);

<span class="comment">-- Oracle</span>
<span class="class">CREATE</span> <span class="type">TABLE</span> xids (
  xid RAW(<span class="integer">144</span>), transactionManagerID <span class="predefined-type">VARCHAR</span>(<span class="integer">64</span>), actionuid RAW(<span class="integer">28</span>)
);
<span class="class">CREATE</span> <span class="directive">UNIQUE</span> <span class="type">INDEX</span> index_xid <span class="keyword">ON</span> xids (xid);

<span class="comment">-- H2</span>
<span class="class">CREATE</span> <span class="type">TABLE</span> xids (
  xid VARBINARY(<span class="integer">144</span>), transactionManagerID <span class="predefined-type">VARCHAR</span>(<span class="integer">64</span>), actionuid VARBINARY(<span class="integer">28</span>)
);
<span class="class">CREATE</span> <span class="directive">UNIQUE</span> <span class="type">INDEX</span> index_xid <span class="keyword">ON</span> xids (xid);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">example of CMR datasource configuration in subsystem</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="sh"># parameter 'connectable' is true for datasource
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml,\
  /subsystem=datasources/data-source=ConnectableCMRDs:add(enabled=true, \
  jndi-name=java:jboss/datasources/ConnectableCMRDs, jta=true, use-java-context=true, \
  use-ccm=true, connectable=true, connection-url=\&quot;jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE\&quot;, \
  driver-name=h2)&quot;

# linking the datasource into the transaction subsystem
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml,\
  /subsystem=transactions/commit-markable-resource=\&quot;java:jboss/datasources/ConnectableCMRDs\&quot;:add&quot;
./bin/jboss-cli.sh &quot;embed-server --server-config=standalone.xml, \
  /subsystem=transactions/commit-markable-resource=\&quot;java:jboss/datasources/ConnectableCMRDs\&quot;:write-attribute(name=name, value=xids), \
  /subsystem=transactions/commit-markable-resource=\&quot;java:jboss/datasources/ConnectableCMRDs\&quot;:write-attribute(name=batch-size, value=10), \  /subsystem=transactions/commit-markable-resource=\&quot;java:jboss/datasources/ConnectableCMRDs\&quot;:write-attribute(name=immediate-cleanup, value=false)&quot;</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">XML configuration example for commit-markable-resources</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;commit-markable-resources&gt;</span>
    <span class="tag">&lt;commit-markable-resource</span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:jboss/datasources/ConnectableCMRDs</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;xid-location</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">xids</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">batch-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">10</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/commit-markable-resource&gt;</span>
  <span class="tag">&lt;/commit-markable-resources&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="log-store"><a class="anchor" href="#log-store"></a><a class="link" href="#log-store">log-store</a></h5>
<div class="paragraph">
<p><code>log-store</code> is a runtime only resource
that can be loaded with a snapshot of the content of the Narayana object store.
The operation <code>/subsystem=transactions/log-store=log-store:probe</code> loads
persisted transaction records from object store and that can be viewed in the model.
Another <code>:probe</code> operation flushes the old data and loads up-to-date records.</p>
</div>
<div class="listingblock">
<div class="title">explore the snapshot of the Narayana object store</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="bash">/subsystem=transactions/log-store=log-store:probe
/subsystem=transactions/log-store=log-store:read-resource(recursive=true, include-runtime=true)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The resulted listing will be similar to the following one.
In this case we can see one transaction with one participant with status <code>PREPARED</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="nowrap">{
  "outcome" =&gt; "success",
  "result" =&gt; {
    "expose-all-logs" =&gt; false,
    "type" =&gt; "default",
    "transactions" =&gt; {"0:ffffc0a80065:-22769d16:60c87436:1a" =&gt; {
      "age-in-seconds" =&gt; "48",
      "id" =&gt; "0:ffffc0a80065:-22769d16:60c87436:1a",
      "jmx-name" =&gt; undefined,
      "type" =&gt; "StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction",
      "participants" =&gt; {"1" =&gt; {
        "eis-product-name" =&gt; undefined,
        "eis-product-version" =&gt; undefined,
        "jmx-name" =&gt; undefined,
        "jndi-name" =&gt; "1",
        "status" =&gt; "PREPARED",
        "type" =&gt; "/StateManager/AbstractRecord/XAResourceRecord"
      }}
    }}
  }
}</pre>
</div>
</div>
<div class="paragraph">
<p>The same content listed as a directory structure when we configure ShadowNoFileLock store</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="nowrap">tree standalone/data/tx-object-store/
standalone/data/tx-object-store/
└── ShadowNoFileLockStore
    └── defaultStore
        ├── EISNAME
        │   └── 0_ffffc0a80065_-22769d16_60c87436_14
        └── StateManager
            └── BasicAction
                └── TwoPhaseCoordinator
                    └── AtomicAction
                        └── 0_ffffc0a80065_-22769d16_60c87436_1a</pre>
</div>
</div>
<div class="sect5">
<h6 id="log-store-transactions-and-participant-operations"><a class="anchor" href="#log-store-transactions-and-participant-operations"></a><a class="link" href="#log-store-transactions-and-participant-operations">log-store transactions and participant operations</a></h6>
<div class="paragraph">
<p>The <code>transactions</code> and <code>participant</code> resources contains several operations
that can be used to work with the content of the object store.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>delete</code> Removes the transaction record from the object store
and calls the <code>XAResource.forget</code> call at all participants.</p>
</li>
<li>
<p><code>refresh</code> Reloads information from the Narayana object store about the participant
and updates the information from object store to model.</p>
</li>
<li>
<p><code>recover</code> This operation switches the participant status to <code>PREPARED</code>.
This is useful mostly for <code>HEURISTIC</code> participant records as <code>HEURISTIC</code> state is
skipped by period recovery processing. Switching the <code>HEURISTIC</code> to <code>PREPARED</code>
means that the periodic recovery will try to finish the record.</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="title">operations at log-store transactions structure</div>
<div class="content">
<pre class="nowrap"># delete of the transaction that subsequently deletes all participants
/subsystem=transactions/log-store=log-store/transactions=0\:ffffc0a80065\:-22769d16\:60c87436\:1a:delete
# delete of the particular participant
/subsystem=transactions/log-store=log-store/transactions=0\:ffffc0a80065\:-22769d16\:60c87436\:1a/participants=1:delete
# refresh and recover
/subsystem=transactions/log-store=log-store/transactions=0\:ffffc0a80065\:-22769d16\:60c87436\:1a/participants=1:refresh
/subsystem=transactions/log-store=log-store/transactions=0\:ffffc0a80065\:-22769d16\:60c87436\:1a/participants=1:recover</pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="client"><a class="anchor" href="#client"></a><a class="link" href="#client">client</a></h5>
<div class="paragraph">
<p>Configuration related to the
<a href="https://github.com/wildfly/wildfly-transaction-client">WildFly Transaction Client</a>.</p>
</div>
<div class="listingblock">
<div class="title">XML configuration example for client</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:transactions:6.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
  ...
  <span class="tag">&lt;client</span> <span class="attribute-name">stale-transaction-time</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">600</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
  ...
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Metrics_SmallRye"><a class="anchor" href="#MicroProfile_Metrics_SmallRye"></a><a class="link" href="#MicroProfile_Metrics_SmallRye">7.10. Metrics Subsystem Configuration</a></h3>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This subsystem exposes only base metrics from the WildFly Management Model and JVM MBeans.</p>
</div>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-metrics">MicroProfile Metrics</a> is provided by
the <em>microprofile-metrics-smallrye</em> subsystem.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="metrics-required-extension-metrics"><a class="anchor" href="#metrics-required-extension-metrics"></a><a class="link" href="#metrics-required-extension-metrics">7.10.1. Extension</a></h4>
<div class="paragraph">
<p>This <code>org.wildfly.extension.metrics</code> extension is included in all the standalone configurations included in the
WildFly distribution as well as the <code>metrics</code> layer.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.metrics"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.metrics:add</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="management-model"><a class="anchor" href="#management-model"></a><a class="link" href="#management-model">7.10.2. Management Model</a></h4>
<div class="paragraph">
<p>The <code>/subsystem=metrics</code> resource defines three attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>security-enabled</code> - a boolean to indicate whether authentication is required to access the HTTP metrics endpoint (described below). By default, it is <code>true</code>. The
standalone configurations explicitly sets it to <code>false</code> to accept unauthenticated access to the HTTP endpoints.</p>
</li>
<li>
<p><code>exposed-subsystems</code> - a list of strings corresponding to the names of subsystems that exposes their metrics in the HTTP metrics endpoints.
By default, it is not defined (there will be no metrics exposed by subsystem. The special wildcard "<strong>" can be used to expose metrics from <em>all</em> subsystems. The standalone
configuration sets this attribute to "</strong>".</p>
</li>
<li>
<p><code>prefix</code> - A string to prepend to WildFly metrics that are exposed by the HTTP endpoint <code>/metrics</code> with the Prometheus output format.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="metrics-metrics-http-endpoint"><a class="anchor" href="#metrics-metrics-http-endpoint"></a><a class="link" href="#metrics-metrics-http-endpoint">7.10.3. HTTP Endpoint</a></h4>
<div class="paragraph">
<p>The Metric HTTP endpoint is accessible on WildFly HTTP management interface <a href="http://localhost:9990/metrics">http://localhost:9990/metrics</a>.</p>
</div>
<div class="paragraph">
<p>Secured access to the HTTP endpoint is controlled by the <code>security-enabled</code> attribute of the <code>/subsystem=metrics</code> resource.
If it is set to <code>true</code>, the HTTP client must be authenticated.</p>
</div>
<div class="paragraph">
<p>If security is disabled, the HTTP endpoint returns a <code>200 OK</code> response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ curl -v http://localhost:9990/metrics
&lt; HTTP/1.1 200 OK
...
# HELP base_classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution
.
# TYPE base_classloader_total_loaded_class_count counter
base_classloader_total_loaded_class_count 10822.0
...</pre>
</div>
</div>
<div class="paragraph">
<p>If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the <code>add-user</code> script. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/metrics
&lt; HTTP/1.1 200 OK
...
# HELP base_classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution
.
# TYPE base_classloader_total_loaded_class_count counter
base_classloader_total_loaded_class_count 10822.0
...</pre>
</div>
</div>
<div class="paragraph">
<p>If the authentication fails, the  server will reply with a <code>401 NOT AUTHORIZED</code> response.</p>
</div>
</div>
<div class="sect3">
<h4 id="exposed-metrics"><a class="anchor" href="#exposed-metrics"></a><a class="link" href="#exposed-metrics">7.10.4. Exposed Metrics</a></h4>
<div class="paragraph">
<p>The HTTP endpoint exposes the following metrics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Base metrics - Metrics from JVM MBeans (read from their JMX MBeans)</p>
</li>
<li>
<p>Vendor metrics - WildFly Metrics from the management model subsystem and deployment subtrees.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The HTTP endpoint exposes the metrics in the Prometheus format only.</p>
</div>
<div class="sect4">
<h5 id="wildfly-metrics-description"><a class="anchor" href="#wildfly-metrics-description"></a><a class="link" href="#wildfly-metrics-description">WildFly Metrics Description</a></h5>
<div class="paragraph">
<p>WildFly metrics names are based on the subsystem that provides them as well as the name of the attribute from the management model.
Their name can also be prepended with a <code>prefix</code> (specified on the <code>/subsystem=metrics</code> resource).
Other information is stored using labels.</p>
</div>
<div class="paragraph">
<p>For example Undertow exposes a metric attribute <code>request-count</code> for every Servlet in an application deployment.
This attribute will be exposed to Prometheus with the name <code>wildfly_undertow_request_count</code>.
Other information such as the name of the Servlet are added to the labels of the metrics.</p>
</div>
<div class="paragraph">
<p>The [helloworld-rs quickstart](<a href="https://github.com/wildfly/quickstart/tree/master/helloworld-rs" class="bare">https://github.com/wildfly/quickstart/tree/master/helloworld-rs</a>) creates a Jakarta RESTful Web Services application
that can be deployed in WildFly.
A corresponding metric will be exposed for it with the name and labels:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>wildfly_undertow_request_count_total{deployment="helloworld-rs.war",servlet="org.jboss.as.quickstarts.rshelloworld.JAXActivator",subdeployment="helloworld-rs.war"}</code></p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Some subsystems (such as <code>undertow</code> or <code>messaging-activemq</code>) do not enable their statistics by default
as they have an impact on performance and memory usage. These subsystems provides a <code>statistics-enabled</code> attribute that must
be set to <code>true</code> to enable them.
For convenience, WildFly standalone configuration provides expressions to enable the statistics by setting a
System property <code>-Dwildfly.statistics-enabled=true</code> to enable statistics on the subsystems provided by the configuration.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Micrometer_Metrics"><a class="anchor" href="#Micrometer_Metrics"></a><a class="link" href="#Micrometer_Metrics">7.11. Micrometer Metrics Subsystem (Preview) Configuration</a></h3>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This subsystem is currently enabled only for WildFly Preview. It replaces the existing metrics subsystem in WildFly, and administrators should not attempt to enable both subsystems concurrently. Attempts to do so will result in a configuration that prevents the server from starting.</p>
</div>
<div class="paragraph">
<p>Standard WildFly continues to use the existing metrics subsystem.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="micrometer-required-extension-metrics"><a class="anchor" href="#micrometer-required-extension-metrics"></a><a class="link" href="#micrometer-required-extension-metrics">7.11.1. Extension</a></h4>
<div class="paragraph">
<p>This <code>org.wildfly.extension.micrometer</code> extension is included in all the standalone configurations included in the
WildFly Preview distribution as well as the <code>micrometer</code> layer.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to any other configuration by adding an
<code>&lt;extension module="org.wildfly.extension.micrometer"/&gt;</code> element as well as
<code>&lt;subsystem xmlns="urn:wildfly:micrometer:1.0" security-enabled="false" exposed-subsystems="*"/&gt;</code> to the configuration&#8217;s
xml file or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.micrometer:add
[standalone@localhost:9990 /] /subsystem=micrometer:add</code></pre>
</div>
</div>
<div class="paragraph">
<p>This subsystem exposes metrics from the WildFly Management Model and JVM MBeans, as well as end-user applications via
the Micrometer API now exposed to applications deployed to the server. Note that this replaces the existing WildFly
Metrics extension, so if you have a reporting dashboard set up to consume these metrics, you carefully read the
<a href="#breaking-changes">Breaking Changes</a> section below for more details.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This subsystem should not be enabled concurrently with the
<a href="MicroProfile_Metrics.html">MicroProfile Metrics Subsystem</a> subsystem, as they both perform the same function.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="management-model-2"><a class="anchor" href="#management-model-2"></a><a class="link" href="#management-model-2">7.11.2. Management Model</a></h4>
<div class="paragraph">
<p>The <code>/subsystem=micrometer</code> resource defines two attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>security-enabled</code> - a boolean to indicate whether authentication is required to access the HTTP metrics endpoint
(described below). By default, it is <code>true</code>. The standalone configurations explicitly sets it to <code>false</code> to accept
unauthenticated access to the HTTP endpoints.</p>
</li>
<li>
<p><code>exposed-subsystems</code> - a list of strings corresponding to the names of subsystems that exposes their metrics in the
HTTP metrics endpoints. By default, it is not defined (there will be no metrics exposed by subsystem. The special
wildcard "*" can be used to expose metrics from <em>all</em> subsystems. The standalone configuration sets this
attribute to "*".</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="micrometer-metrics-http-endpoint"><a class="anchor" href="#micrometer-metrics-http-endpoint"></a><a class="link" href="#micrometer-metrics-http-endpoint">7.11.3. HTTP Endpoint</a></h4>
<div class="paragraph">
<p>The Micrometer HTTP endpoint is accessible on WildFly HTTP management interface <a href="http://localhost:9990/metrics" class="bare">http://localhost:9990/metrics</a>.</p>
</div>
<div class="paragraph">
<p>Secured access to the HTTP endpoint is controlled by the <code>security-enabled</code> attribute of the <code>/subsystem=micrometer</code> resource.
If it is set to <code>true</code>, the HTTP client must be authenticated.</p>
</div>
<div class="paragraph">
<p>If security is disabled, the HTTP endpoint returns a <code>200 OK</code> response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ curl -v http://localhost:9990/metrics
&lt; HTTP/1.1 200 OK
...
# HELP jvm_uptime_seconds Displays the uptime of the Java virtual machine
# TYPE jvm_uptime_seconds gauge
jvm_uptime_seconds 215.505
...</pre>
</div>
</div>
<div class="paragraph">
<p>If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the <code>add-user</code> script. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/metrics
&lt; HTTP/1.1 200 OK
...
# HELP jvm_uptime_seconds Displays the uptime of the Java virtual machine
# TYPE jvm_uptime_seconds gauge
jvm_uptime_seconds 215.505
...</pre>
</div>
</div>
<div class="paragraph">
<p>If the authentication fails, the server will reply with a <code>401 NOT AUTHORIZED</code> response.</p>
</div>
</div>
<div class="sect3">
<h4 id="exposed-metrics-2"><a class="anchor" href="#exposed-metrics-2"></a><a class="link" href="#exposed-metrics-2">7.11.4. Exposed Metrics</a></h4>
<div class="paragraph">
<p>The HTTP endpoint exposes the following metrics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Metrics from JVM MBeans (read directly from the JMX MBeans)</p>
</li>
<li>
<p>WildFly metrics from the management model subsystem and deployment subtrees.</p>
</li>
<li>
<p>Any application-specific metrics provided via the injected Micrometer <code>MeterRegistry</code> instance.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The HTTP endpoint exposes the metrics in the Prometheus format only.</p>
</div>
<div class="sect4">
<h5 id="wildfly-metrics-description-2"><a class="anchor" href="#wildfly-metrics-description-2"></a><a class="link" href="#wildfly-metrics-description-2">WildFly Metrics Description</a></h5>
<div class="paragraph">
<p>WildFly metrics names are based on the subsystem that provides them, as well as the name of the attribute from the
management model.</p>
</div>
<div class="paragraph">
<p>For example Undertow exposes a metric attribute <code>request-count</code> for every Servlet in an application deployment.
This attribute will be exposed with the name <code>undertow_request_count</code>. Other information such as the name
of the <code>Servlet</code> are added to the tags of the metric.</p>
</div>
<div class="paragraph">
<p>The <a href="https://github.com/wildfly/quickstart/tree/master/helloworld-rs">helloworld-rs quickstart</a> creates a Jakarta RESTful
Web Services application that can be deployed in WildFly. A corresponding metric will be exposed for it with the name and
tags:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>undertow_request_count_total{app="helloworld-rs.war",deployment="helloworld-rs.war",name="org.jboss.as.quickstarts.rshelloworld.JAXActivator",subdeployment="helloworld-rs.war",type="servlet",} 4.0</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Some subsystems (such as <code>undertow</code> or <code>messaging-activemq</code>) do not enable their statistics by default
as they have an impact on performance and memory usage. These subsystems provide a <code>statistics-enabled</code> attribute that must
be set to <code>true</code> to enable them. For convenience, WildFly standalone configuration provides expressions to enable the
statistics by setting a System property <code>-Dwildfly.statistics-enabled=true</code> to enable statistics on the subsystems
provided by the configuration.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="use-in-applications"><a class="anchor" href="#use-in-applications"></a><a class="link" href="#use-in-applications">7.11.5. Use in Applications</a></h4>
<div class="paragraph">
<p>Unlike the previous metrics system, this new extension exposes an API (that of <a href="https://micrometer.io">Micrometer</a>) to
applications in order to allow developers to record and export metrics out of the box. To do so, application developers
will need to inject a <code>MeterRegistry</code> instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">com.redhat.wildfly.micrometerdemo</span>;

<span class="keyword">import</span> <span class="include">jakarta.enterprise.context.RequestScoped</span>;
<span class="keyword">import</span> <span class="include">jakarta.inject.Inject</span>;
<span class="keyword">import</span> <span class="include">jakarta.ws.rs.GET</span>;
<span class="keyword">import</span> <span class="include">jakarta.ws.rs.Path</span>;
<span class="keyword">import</span> <span class="include">io.micrometer.core.instrument.MeterRegistry</span>;

<span class="annotation">@RequestScoped</span>
<span class="annotation">@Path</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">/endpoint</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">Endpoint</span> {
    <span class="annotation">@Inject</span>
    <span class="directive">private</span> MeterRegistry registry;

    <span class="annotation">@GET</span>
    <span class="directive">public</span> <span class="predefined-type">String</span> method() {
        registry.counter(<span class="string"><span class="delimiter">&quot;</span><span class="content">dummy</span><span class="delimiter">&quot;</span></span>).increment();
        <span class="keyword">return</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">Counter is </span><span class="delimiter">&quot;</span></span> + registry.counter(<span class="string"><span class="delimiter">&quot;</span><span class="content">dummy</span><span class="delimiter">&quot;</span></span>).count();
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This provides the application with a <code>MeterRegistry</code> instance that will have any recorded metrics exported with the
system metrics WildFly already exposes. There is no need for an application to include the Micrometer dependencies in the
application archive, as they are provided by the server out-of-the-box:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
    <span class="tag">&lt;groupId&gt;</span>io.micrometer<span class="tag">&lt;/groupId&gt;</span>
    <span class="tag">&lt;artifactId&gt;</span>micrometer-core<span class="tag">&lt;/artifactId&gt;</span>
    <span class="tag">&lt;version&gt;</span>${version.micrometer}<span class="tag">&lt;/version&gt;</span>
    <span class="tag">&lt;scope&gt;</span>provided<span class="tag">&lt;/scope&gt;</span>
<span class="tag">&lt;/dependency&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="breaking-changes"><a class="anchor" href="#breaking-changes"></a><a class="link" href="#breaking-changes">7.11.6. Breaking Changes</a></h4>
<div class="paragraph">
<p>This new subsystem does bring some breaking changes in order to provide metrics in a manner more consistent with general industry standards.</p>
</div>
<div class="sect4">
<h5 id="no-more-prefixes"><a class="anchor" href="#no-more-prefixes"></a><a class="link" href="#no-more-prefixes">No more prefixes</a></h5>
<div class="paragraph">
<p>This new extension removes the <code>base</code> and <code>vendor</code> prefixes, in accordance with
Prometheus conventions. For example, metrics such as <code>base_classloader_loadedClasses</code> will now simply be <code>classloader_loaded_classes</code>.</p>
</div>
<div class="paragraph">
<p>Likewise, the <code>prefix</code> configuration property has been removed, as the prefixing of meter names is inconsistent with Prometheus best practices. Tags are the preferred way to handle differentiating metrics of the same name.</p>
</div>
</div>
<div class="sect4">
<h5 id="more-consistent-name-formatting"><a class="anchor" href="#more-consistent-name-formatting"></a><a class="link" href="#more-consistent-name-formatting">More consistent name formatting</a></h5>
<div class="paragraph">
<p>In previous releases, one might see a meter named <code>base_classloader_loadedClasses</code> or <code>vendor_BufferPool_used_memory</code>. These have been renamed to <code>classload_loaded_classes</code> and <code>buffer_pool_used_memory</code> respectively. The "snake casing" of the names should now be consistent across all the meter names.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Observability_Tracing"><a class="anchor" href="#Observability_Tracing"></a><a class="link" href="#Observability_Tracing">7.12. OpenTelemetry Subsystem Configuration</a></h3>
<div class="sect3">
<h4 id="required-extension-opentelemetry"><a class="anchor" href="#required-extension-opentelemetry"></a><a class="link" href="#required-extension-opentelemetry">7.12.1. Extension</a></h4>
<div class="paragraph">
<p>This extension is not included in any of the standalone configurations included in the WildFly distribution.
To enable, the administrator must run the following CLI commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code> $ jboss-cli.sh -c &quot;/extension=org.wildfly.extension.opentelemetry:add()&quot;
 $ jboss-cli.sh -c &quot;/subsystem=opentelemetry:add()&quot;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuration-2"><a class="anchor" href="#configuration-2"></a><a class="link" href="#configuration-2">7.12.2. Configuration</a></h4>
<div class="paragraph">
<p>Systems administrators can configure a number of aspects of OpenTelemetry: the exporter, span processor, and sampler.</p>
</div>
<div class="sect4">
<h5 id="exporter"><a class="anchor" href="#exporter"></a><a class="link" href="#exporter">Exporter</a></h5>
<div class="paragraph">
<p>The exporter can be selected and configured using the <code>exporter</code> child element, which supports these attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>exporter</code>: WildFly supports two different exporters:</p>
<div class="ulist">
<ul>
<li>
<p><code>jaeger</code>: The default exporter</p>
</li>
<li>
<p><code>otlp</code>: The OpenTelemetry protocol</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>endpoint</code>: The URL via which OpenTelemetry will push traces. The default is Jaeger&#8217;s gRPC-based endpoint, <a href="http://localhost:14250" class="bare">http://localhost:14250</a></p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="span-processor"><a class="anchor" href="#span-processor"></a><a class="link" href="#span-processor">Span Processor</a></h5>
<div class="paragraph">
<p>The span process is configured via the <code>span-processor</code> element, which supports the following attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>type</code>: The type of span processor to use.</p>
<div class="ulist">
<ul>
<li>
<p><code>batch</code>: The default processor, which sends traces in batches as configured via the remaining attributes</p>
</li>
<li>
<p><code>simple</code>: Traces are pushed to the exporter as they finish.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>batch-delay</code>: The amount of time, in milliseconds, to wait before traces are published (default: 5000)</p>
</li>
<li>
<p><code>max-queue-size</code>: The maximum size of the queue before traces are dropped (default: 2048)</p>
</li>
<li>
<p><code>max-export-batch-size</code>: The maximum number of traces that are published in each batch, which must be smaller or equal to `max-queue-size (default: 512)</p>
</li>
<li>
<p><code>export-timeout</code>: The maximum amount of time in milliseconds to allow for an export to complete before being cancelled (default: 30000)</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="sampler"><a class="anchor" href="#sampler"></a><a class="link" href="#sampler">Sampler</a></h5>
<div class="paragraph">
<p>The sampler is configured via the <code>sampler</code> element:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>type</code>: The type of sampler to use</p>
<div class="ulist">
<ul>
<li>
<p><code>on</code>: Always on (all traces are recorded)</p>
</li>
<li>
<p><code>off</code>: Always off (no traces are recorded)</p>
</li>
<li>
<p><code>ratio</code>: Return a ratio of the traces (e.g., 1 trace in 10000).</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>ratio</code>: The value used to configure the <code>ratio</code> sampler, which must be within [0.0, 1.0].For example, if 1 trace in 10,000 is to be exported, this value would be <code>0.0001</code>.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="example-configuration"><a class="anchor" href="#example-configuration"></a><a class="link" href="#example-configuration">Example Configuration</a></h5>
<div class="paragraph">
<p>The following XML is an example of the full configuration, including default values (WildFly does not typically persist
default values, so what you see in the configuration file may look different):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:opentelemetry:1.0</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">service-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">example</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;exporter</span>
        <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jaeger</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">endpoint</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:14250</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;span-processor</span>
        <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">batch</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">batch-delay</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">4500</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">max-queue-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">128</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">max-export-batch-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">512</span><span class="delimiter">&quot;</span></span>
        <span class="attribute-name">export-timeout</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">45</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;sampler</span>
        <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">on</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="application-usage"><a class="anchor" href="#application-usage"></a><a class="link" href="#application-usage">7.12.3. Application Usage</a></h4>
<div class="paragraph">
<p>All incoming REST requests are automatically traced, so no work needs be done in user applications.If a REST request is received and the OpenTelemetry context propagation header (<code>traceparent</code>) is present, the request will traced as part of the remote trace context automatically.</p>
</div>
<div class="paragraph">
<p>Likewise, all Jakarta REST Client calls will have the trace context added to outgoing request headers so that requests to external applications can be traced correctly (assuming the remote system properly handles OpenTelemetry trace context propagation).If the REST Client call is made to another application on the local WildFly server, or a remote server of the same version or later, the trace context will propagate automatically as described above.</p>
</div>
<div class="paragraph">
<p>While automatic tracing may be sufficient in many cases, it will often be desirable to have traces occur throughout the user application.To support that, WildFly makes available the <code>io.opentelemetry.api.OpenTelemetry</code> and
<code>io.opentelemetry.api.trace.Tracer</code> instances, via CDI injection.A user application, then is able to create arbitrary spans as part of the server-managed trace:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Path</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">/myEndpoint</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyEndpoint</span> {
    <span class="annotation">@Inject</span>
    <span class="directive">private</span> Tracer tracer;

    <span class="annotation">@GET</span>
    <span class="directive">public</span> Response doSomeWork() {
        <span class="directive">final</span> Span span = tracer.spanBuilder(<span class="string"><span class="delimiter">&quot;</span><span class="content">Doing some work</span><span class="delimiter">&quot;</span></span>)
                .startSpan();
        span.makeCurrent();
        doSomeMoreWork();
        span.addEvent(<span class="string"><span class="delimiter">&quot;</span><span class="content">Make request to external system.</span><span class="delimiter">&quot;</span></span>);
        makeExternalRequest();
        span.addEvent(<span class="string"><span class="delimiter">&quot;</span><span class="content">All the work is done.</span><span class="delimiter">&quot;</span></span>);
        span.end();

        <span class="keyword">return</span> Response.ok().build();
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="interaction-with-microprofile-opentracing"><a class="anchor" href="#interaction-with-microprofile-opentracing"></a><a class="link" href="#interaction-with-microprofile-opentracing">7.12.4. Interaction with MicroProfile OpenTracing</a></h4>
<div class="paragraph">
<p>If you have the MicroProfile OpenTracing subsystem enabled (e.g., via the MicroProfile configuration), you may see duplicate traces exported for JAX-RS calls, for example.
This is because both OpenTracing and OpenTelemetry have instrumented the endpoints to enable tracing, and both subsystems are configured to export traces to a collector such as Jaeger.
Likely, this is not desirable, so if you would like to use OpenTelemetry for tracing, it is advisable to remove the OpenTracing subsystem:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code> $ jboss-cli.sh -c &quot;/subsystem=microprofile-opentracing-smallrye:remove()&quot;
 $ jboss-cli.sh -c &quot;/extension=org.wildfly.extension.microprofile.opentracing-smallrye:remove()&quot;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you leave both subsystems enabled, though, WildFly will continue to function normally.
The only difference you will see is the duplicate trace export mentioned above.</p>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-2"><a class="anchor" href="#component-reference-2"></a><a class="link" href="#component-reference-2">7.12.5. Component Reference</a></h4>
<div class="paragraph">
<p>OpenTelemetry support is provided via the <a href="https://opentelemetry.io">OpenTelemetry</a> project.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Health"><a class="anchor" href="#Health"></a><a class="link" href="#Health">7.13. Health Subsystem Configuration</a></h3>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This subsystem exposes only healthiness checks for the WildFly runtime.
Support for <a href="https://microprofile.io/project/eclipse/microprofile-health">MicroProfile Health</a> is provided by
the <em>microprofile-health-smallrye</em> subsystem.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="health_required-extension-metrics"><a class="anchor" href="#health_required-extension-metrics"></a><a class="link" href="#health_required-extension-metrics">7.13.1. Extension</a></h4>
<div class="paragraph">
<p>This <code>org.wildfly.extension.health</code> extension is included in all the standalone configurations included in the
WildFly distribution as well as the <code>health</code> layer.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.health"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.health:add</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="management-model-3"><a class="anchor" href="#management-model-3"></a><a class="link" href="#management-model-3">7.13.2. Management Model</a></h4>
<div class="paragraph">
<p>The <code>/subsystem=health</code> resource defines one attribute:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>security-enabled</code> - a boolean to indicate whether authentication is required to access the HTTP health endpoint (described below). By default, it is <code>true</code>. The
standalone configurations explicitly sets it to <code>false</code> to accept unauthenticated access to the HTTP endpoints.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="health-http-endpoint"><a class="anchor" href="#health-http-endpoint"></a><a class="link" href="#health-http-endpoint">7.13.3. HTTP Endpoint</a></h4>
<div class="paragraph">
<p>The Health HTTP endpoint is accessible on the WildFly HTTP management interface <a href="http://localhost:9990/health">http://localhost:9990/health</a>.</p>
</div>
<div class="paragraph">
<p>The <code>health</code> subsystem registers three HTTP endpoints:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/health</code> to test both the liveness and readiness of the application server.</p>
</li>
<li>
<p><code>/health/live</code> to test the liveness of the application server</p>
</li>
<li>
<p><code>/health/ready</code> to test the readiness of the application server.</p>
</li>
<li>
<p><code>/health/started</code> to test the startup of the application server.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The Health HTTP endpoints are accessible on the WildFly HTTP management interface (e.g. <a href="http://localhost:9990/health">http://localhost:9990/health</a>).</p>
</div>
<div class="paragraph">
<p>If the application server is healthy, it will return a <code>200 OK</code> response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v http://localhost:9990/health
&lt; HTTP/1.1 200 OK</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the application server  is not healthy, it returns <code>503 Service Unavailable</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v http://localhost:9990/health
&lt; HTTP/1.1 503 Service Unavailable</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="secured-access-to-the-http-endpoints"><a class="anchor" href="#secured-access-to-the-http-endpoints"></a><a class="link" href="#secured-access-to-the-http-endpoints">Secured Access to the HTTP endpoints</a></h5>
<div class="paragraph">
<p>Secured access to the HTTP endpoint is controlled by the <code>security-enabled</code> attribute.
If it is set to <code>true</code>, the HTTP client must be authenticated.</p>
</div>
<div class="paragraph">
<p>If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the <code>add-user</code> script. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/health
&lt; HTTP/1.1 200 OK</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the authentication fails, the  server will reply with a <code>401 NOT AUTHORIZED</code> response.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The HTTP response contains additional information with individual outcomes for each probe that determined the healthiness.
This is informational only and the HTTP response code is the only relevant data to determine the healthiness of the application server.
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="default-server-procedures"><a class="anchor" href="#default-server-procedures"></a><a class="link" href="#default-server-procedures">Default Server Procedures</a></h5>
<div class="paragraph">
<p>WildFly provides some readiness procedures that are checked to determine if the application server is ready to serve requests:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>boot-errors</code> checks that there were no errors during the server boot sequence</p>
</li>
<li>
<p><code>deployments-status</code> checks that all deployments were deployed without errors</p>
</li>
<li>
<p><code>server-state</code> checks that the server state is <code>running</code></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Config_SmallRye"><a class="anchor" href="#MicroProfile_Config_SmallRye"></a><a class="link" href="#MicroProfile_Config_SmallRye">7.14. MicroProfile Config Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-config">MicroProfile Config</a> is provided by
 the <em>microprofile-config-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-config-smallrye"><a class="anchor" href="#required-extension-microprofile-config-smallrye"></a><a class="link" href="#required-extension-microprofile-config-smallrye">7.14.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is included in the standard configurations included in the
WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.microprofile.config-smallrye"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.config-smallrye:add</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="supported-configsources"><a class="anchor" href="#supported-configsources"></a><a class="link" href="#supported-configsources">7.14.2. Supported ConfigSources</a></h4>
<div class="paragraph">
<p>In addition to the default <code>ConfigSources</code> specified by the MicroProfile Config specification
(environment variables, System properties and <code>META-INF/microprofile-config.properties</code> file), the
<code>microprofile-config-smallrye</code> provides additional types of <code>ConfigSource</code></p>
</div>
<div class="sect4">
<h5 id="configsource-from-properties"><a class="anchor" href="#configsource-from-properties"></a><a class="link" href="#configsource-from-properties">ConfigSource from Properties</a></h5>
<div class="paragraph">
<p>You can store properties directly in a <code>config-source</code> in the subsystem by using the <code>properties</code>
attribute when you add the <code>config-source</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=microprofile-config-smallrye/config-source=props:add(properties={&quot;prop1&quot; = &quot;foo&quot;, &quot;prop2&quot; = &quot;bar&quot;})</code></pre>
</div>
</div>
<div class="paragraph">
<p>This results in the XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-config-smallrye:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;config-source</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">props</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">prop1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">foo</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">prop2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bar</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/config-source&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="configsource-from-directory"><a class="anchor" href="#configsource-from-directory"></a><a class="link" href="#configsource-from-directory">ConfigSource from Directory</a></h5>
<div class="paragraph">
<p>You can also read properties from a directory where each file is the name of
a property and the file content is the value of the property.</p>
</div>
<div class="paragraph">
<p>For example, let&#8217;s imagine that the directory <code>/etc/config/numbers-app/</code> contains 2 files:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the <code>num.size</code> file contains the value <code>5</code></p>
</li>
<li>
<p>the <code>num.max</code> file contains the value <code>100</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>We can create a config-source` to access these properties by using the operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/numbers-app})</code></pre>
</div>
</div>
<div class="paragraph">
<p>This results in the XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-config-smallrye:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;config-source</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">file-props</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;dir</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/etc/config/numbers-app</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/config-source&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>With that configuration, any application deployed in WildFly can use the <code>num.size</code> and
<code>num.max</code> properties that are stored in the directory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Inject</span>
<span class="annotation">@ConfigProperty</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">num.size</span><span class="delimiter">&quot;</span></span>)
<span class="type">int</span> numSize; <i class="conum" data-value="1"></i><b>(1)</b>

<span class="annotation">@Inject</span>
<span class="annotation">@ConfigProperty</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">num.max</span><span class="delimiter">&quot;</span></span>)
<span class="type">int</span> numMax; <i class="conum" data-value="2"></i><b>(2)</b></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>will be set to 5</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>will be set to 100</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This corresponds to the layout used by <a href="https://docs.openshift.com/enterprise/3.2/dev_guide/configmaps.html">OpenShift ConfigMaps</a>.
The <code>dir</code> value corresponds to the <code>mountPath</code> in the ConfigMap definition in OpenShift or Kubernetes.
</td>
</tr>
</table>
</div>
<div class="sect5">
<h6 id="configsources-from-root-directory"><a class="anchor" href="#configsources-from-root-directory"></a><a class="link" href="#configsources-from-root-directory">ConfigSources from Root directory</a></h6>
<div class="paragraph">
<p>You can also point to a root directory by adjusting the examples in the preceding section to include
<code>root=true</code> when defining them. Top level directories within this root directory each become an
individual <code>ConfigSource</code> reading from a directory similar to what we saw earlier in
<a href="#configsource-from-directory">ConfigSource from Directory</a>. Any directories below the top-level
directories are ignored. Also, any files in the root directory are ignored; only files in the top
level directories within the root directory will be used for the configuration.</p>
</div>
<div class="paragraph">
<p>This is especially useful when running on OpenShift where constructs such as <code>ConfigMap</code> and
<code>ServiceBinding</code> instances get mapped under
a common known location. For example if there are two <code>ConfigMap</code> instances (for this example,
we will call them <code>map-a</code>, and <code>map-b</code>) used by your application pod, they will
each get mapped under <code>/etc/config</code>. So you would have <code>/etc/config/map-a</code> and <code>/etc/config/map-b</code>
directories.</p>
</div>
<div class="paragraph">
<p>Each of these directories will have files where the file name is the name of the property and the file
content is the value of the property, like we saw earlier.</p>
</div>
<div class="paragraph">
<p>We can thus simply run the following CLI command to pick up all these child directories as
a <code>ConfigSource</code> each:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=microprofile-config-smallrye/config-source=config-map-root:add(dir={path=/etc/config, root=true})</code></pre>
</div>
</div>
<div class="paragraph">
<p>This results in the XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-config-smallrye:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;config-source</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">config-map-root</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;dir</span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/etc/config</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">root</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/config-source&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Assuming the <code>/etc/config</code> directory contains the <code>map-a</code> and <code>map-b</code> directories we are using
for this example, the above is analogous to doing:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/map-a})
/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/map-b})</pre>
</div>
</div>
<div class="paragraph">
<p>Specifying the root directory rather than each individual directory removes the need to know the
exact names of each entry under the common parent directory (this is especially useful in some
OpenShift scenarios where the names of these directories are auto-generated).</p>
</div>
<div class="paragraph">
<p>The situation where two <code>ConfigSource</code> entries under the same root both contain the same property
should be avoided. However, to make this situation deterministic, the directories representing each
<code>ConfigSource</code> are sorted by their name according to standard Java sorting rules before doing the
lookup of values. To make this more concrete, if we have the following entries:
* <code>/etc/config/map-a/name</code> contains <code>kabir</code>
* <code>/etc/config/map-b/name</code> contains <code>jeff</code></p>
</div>
<div class="paragraph">
<p>Since <code>map-a</code> will come before <code>map-b</code> after sorting, in the following scenario <code>kabir</code> (coming from
<code>map-a</code>) will be injected for the following <code>username</code> field:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Inject</span>
<span class="annotation">@ConfigProperty</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>)
<span class="predefined-type">String</span> username;</code></pre>
</div>
</div>
<div class="paragraph">
<p>You may override this default sorting by including a file called <code>config_ordinal</code> in a directory. The
ordinal specified in that file will be used for config values coming from that directory. Building
on our previous example, if we had:
* <code>/etc/config/map-a/config_ordinal</code> contains <code>120</code>
* <code>/etc/config/map-b/config_ordinal</code> contains <code>140</code></p>
</div>
<div class="paragraph">
<p>Since now <code>map-b</code> has a higher ordinal (<code>140</code>) than <code>map-a</code> (<code>120</code>), we will instead inject the value
<code>jeff</code> for the earlier <code>username</code> field.</p>
</div>
<div class="paragraph">
<p>If there is no <code>config_ordinal</code> file in a top-level directory under the root directory, the
ordinal used when specifying the <code>ConfigSource</code> will be used for that directory.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="configsource-from-class"><a class="anchor" href="#configsource-from-class"></a><a class="link" href="#configsource-from-class">ConfigSource from Class</a></h5>
<div class="paragraph">
<p>You can create a specific type of <code>ConfigSource</code> implementation by creating a <code>config-source</code> resource
with a <code>class</code> attribute.</p>
</div>
<div class="paragraph">
<p>For example, you can provide an implementation of <code>org.eclipse.microprofile.config.spi.ConfigSource</code>
that is named <code>org.example.MyConfigSource</code> and provided by a JBoss module named <code>org.example</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>/subsystem=microprofile-config-smallrye/config-source=my-config-source:add(class={name=org.example.MyConfigSource, module=org.example})</pre>
</div>
</div>
<div class="paragraph">
<p>This results in the XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-config-smallrye:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;config-source</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">my-config-source</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.example.MyConfigSource</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.example</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/config-source&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>All properties from this <code>ConfigSource</code> will be available to any WildFly deployment.</p>
</div>
</div>
<div class="sect4">
<h5 id="configsourceprovider-from-class"><a class="anchor" href="#configsourceprovider-from-class"></a><a class="link" href="#configsourceprovider-from-class">ConfigSourceProvider from Class</a></h5>
<div class="paragraph">
<p>You can create a specific type of <code>ConfigSourceProvider</code> implementation by creating a <code>config-source-provider</code> resource
with a <code>class</code> attribute.</p>
</div>
<div class="paragraph">
<p>For example, you can provide an implementation of <code>org.eclipse.microprofile.config.spi.ConfigSourceProvider</code>
that is named <code>org.example.MyConfigSourceProvider</code> and provided by a JBoss module named <code>org.example</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})</pre>
</div>
</div>
<div class="paragraph">
<p>This results in the XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-config-smallrye:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;config-source-provider</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">my-config-source-provider</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
         <span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.example.MyConfigSourceProvider</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.example</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/config-source-provider&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>All properties from the <code>ConfigSource`s provided by this `ConfigSourceProvider</code> will be available to any WildFly deployment.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="deployment"><a class="anchor" href="#deployment"></a><a class="link" href="#deployment">7.14.3. Deployment</a></h4>
<div class="paragraph">
<p>Applications that are deployed in WildFly must have Jakarta Contexts and Dependency Injection enabled (e.g. with a <code>META-INF/beans.xml</code>
or by having Jakarta Contexts and Dependency Injection Bean annotation) to be able to use MicroProfile Config in their code.</p>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-3"><a class="anchor" href="#component-reference-3"></a><a class="link" href="#component-reference-3">7.14.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile Config implementation is provided by the SmallRye Config project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-config">MicroProfile Config</a></p>
</li>
<li>
<p><a href="http://github.com/smallrye/smallrye-config/">SmallRye Config</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Health_SmallRye"><a class="anchor" href="#MicroProfile_Health_SmallRye"></a><a class="link" href="#MicroProfile_Health_SmallRye">7.15. MicroProfile Health Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-health">MicroProfile Health</a> is provided by
 the <em>microprofile-health-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-health-smallrye"><a class="anchor" href="#required-extension-microprofile-health-smallrye"></a><a class="link" href="#required-extension-microprofile-health-smallrye">7.15.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is included in the standalone-microprofile configurations included in the
WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.microprofile.health-smallrye"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /]/extension=org.wildfly.extension.microprofile.health-smallrye:add</code></pre>
</div>
</div>
<div class="paragraph">
<p>It depends on the base health extension <code>org.wildfly.extension.health</code> that must be installed.</p>
</div>
</div>
<div class="sect3">
<h4 id="management-operations"><a class="anchor" href="#management-operations"></a><a class="link" href="#management-operations">7.15.2. Management Operations</a></h4>
<div class="paragraph">
<p>The healthiness of the application server can be queried by calling 3 different operations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>check</code> to check both the liveness and readiness of the runtime</p>
</li>
<li>
<p><code>check-live</code> to check only the liveness of the runtime</p>
</li>
<li>
<p><code>check-ready</code> to check only the readiness of the runtime</p>
</li>
<li>
<p><code>check-started</code> to check only the startup of the runtime</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=microprofile-health-smallrye:check
{
    &quot;outcome&quot; =&gt; &quot;success&quot;, <i class="conum" data-value="1"></i><b>(1)</b>
    &quot;result&quot; =&gt; {
        &quot;status&quot; =&gt; &quot;UP&quot;, <i class="conum" data-value="2"></i><b>(2)</b>
        &quot;checks&quot; =&gt; [
            {
                &quot;name&quot; =&gt; &quot;server-state&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;,
                &quot;data&quot; =&gt; {&quot;value&quot; =&gt; &quot;running&quot;}
            },
            {
                &quot;name&quot; =&gt; &quot;empty-startup-checks&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;
            },
            {
                &quot;name&quot; =&gt; &quot;empty-readiness-checks&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;
            },
            {
                &quot;name&quot; =&gt; &quot;boot-errors&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;
            },
            {
                &quot;name&quot; =&gt; &quot;empty-liveness-checks&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;
            },
            {
                &quot;name&quot; =&gt; &quot;deployments-status&quot;,
                &quot;status&quot; =&gt; &quot;UP&quot;
            }
        ]
    }
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>this <code>outcome</code> means that the management operation is successful</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>this <code>status</code> corresponds to the health check, <code>UP</code> if the application server is healthy, <code>DOWN</code> else.</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="http-endpoints"><a class="anchor" href="#http-endpoints"></a><a class="link" href="#http-endpoints">7.15.3. HTTP Endpoints</a></h4>
<div class="paragraph">
<p>The MicroProfile Health Check specifications defines three HTTP endpoints:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/health</code> to test both the liveness and readiness of the application server.</p>
</li>
<li>
<p><code>/health/live</code> to test the liveness of the application server</p>
</li>
<li>
<p><code>/health/ready</code> to test the readiness of the application server.</p>
</li>
<li>
<p><code>/health/started</code> to test the startup of the application server.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The Health HTTP endpoints are accessible on WildFly HTTP management interface (e.g. <a href="http://localhost:9990/health">http://localhost:9990/health</a>).</p>
</div>
<div class="paragraph">
<p>If the application server is healthy, it will return a <code>200 OK</code> response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v http://localhost:9990/health
&lt; HTTP/1.1 200 OK
...
{&quot;status&quot;:&quot;UP&quot;,&quot;checks&quot;:[{&quot;name&quot;:&quot;server-state&quot;,&quot;status&quot;:&quot;UP&quot;,&quot;data&quot;:{&quot;value&quot;:&quot;running&quot;}},{&quot;name&quot;:&quot;empty-startup-checks&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;empty-readiness-checks&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;boot-errors&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;empty-liveness-checks&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;deployments-status&quot;,&quot;status&quot;:&quot;UP&quot;}]}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the application server is not healthy, it returns <code>503 Service Unavailable</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v http://localhost:9990/health
&lt; HTTP/1.1 503 Service Unavailable
...
{&quot;outcome&quot;:&quot;DOWN&quot;,&quot;checks&quot;:[{&quot;name&quot;:&quot;myFailingProbe&quot;,&quot;state&quot;:&quot;DOWN&quot;,&quot;data&quot;:{&quot;foo&quot;:&quot;bar&quot;}}]}</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="secured-access-to-the-http-endpoints-2"><a class="anchor" href="#secured-access-to-the-http-endpoints-2"></a><a class="link" href="#secured-access-to-the-http-endpoints-2">Secured Access to the HTTP endpoints</a></h5>
<div class="paragraph">
<p>Secured access to the HTTP endpoint is controlled by the <code>security-enabled</code> attribute of the <code>/subsystem=microprofile-health-smallrye</code> resource.
The value of this attribute will override the <code>security-enabled</code> attribute of the <code>/subsystem=health</code> resource (documented in <a href="#health-http-endpoint">Health subsystem configuration guide</a>).
If it is set to <code>true</code>, the HTTP client must be authenticated.</p>
</div>
<div class="paragraph">
<p>If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the <code>add-user</code> script. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/health
&lt; HTTP/1.1 200 OK
...
{&quot;status&quot;:&quot;UP&quot;,&quot;checks&quot;:[{&quot;name&quot;:&quot;empty-liveness-checks&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;server-state&quot;,&quot;status&quot;:&quot;UP&quot;,&quot;data&quot;:{&quot;value&quot;:&quot;running&quot;}},{&quot;name&quot;:&quot;boot-errors&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;deployments-status&quot;,&quot;status&quot;:&quot;UP&quot;},{&quot;name&quot;:&quot;empty-readiness-checks&quot;,&quot;status&quot;:&quot;UP&quot;}]}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the authentication fails, the  server will reply with a <code>401 NOT AUTHORIZED</code> response.</p>
</div>
</div>
<div class="sect4">
<h5 id="default-server-procedures-2"><a class="anchor" href="#default-server-procedures-2"></a><a class="link" href="#default-server-procedures-2">Default Server Procedures</a></h5>
<div class="paragraph">
<p>WildFly provides some readiness procedures that are checked to determine if the application server is ready to serve requests:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>boot-errors</code> checks that there were no errors during the server boot sequence</p>
</li>
<li>
<p><code>deployments-status</code> checks that all deployments were deployed without errors</p>
</li>
<li>
<p><code>server-state</code> checks that the server state is <code>running</code></p>
</li>
<li>
<p><code>empty-readiness-checks</code> determines the status when there are no readiness check procedures deployed to the server. The outcome of this procedure is determined by the <code>empty-readiness-checks-status</code> attribute. If the attribute is
<code>UP</code> (by default), the server can be ready when there are no readiness checks in the deployments. Setting the <code>empty-readiness-checks-status</code> attribute to <code>DOWN</code> will make this procedure fail when there are no readiness checks in the deployments.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If a deployment does not provide any readiness checks, WildFly will automatically add one for each deployment (named <code>ready-&lt;deployment name&gt;</code>) which always returns <code>UP</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This allows applications that does not provide readiness checks to still be able to inform cloud containers when they are ready to serve requests.
Setting <code>empty-readiness-checks-status</code> to <code>DOWN</code> ensures that the server will not be ready until the application is deployed. At that time, the <code>ready-&lt;deployment name&gt;</code>
will be added (which returns <code>UP</code>) and the <code>empty-readiness-checks</code> procedure will no longer be checked as there is now a readiness check procedure provided either by the deployment or by the server.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>WildFly also provide a liveness procedure that is checked to determine if the application server is live:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>empty-liveness-checks</code> determines the status when there are no liveness check procedures deployed to the server. The outcome of this procedure is determined by the <code>empty-liveness-checks-status</code> attribute. If the attribute is
<code>UP</code> (by default), the server can be live when there are no liveness checks in the deployments.  Setting the <code>empty-liveness-checks-status</code> attribute to <code>DOWN</code> will make this procedure fail when there are no liveness checks in the deployments.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>WildFly also provides a similar procedure for what concerns startup checks:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>empty-startup-checks</code> determines the status when there are no startup check procedures deployed to the server. The outcome of this procedure is determined by the <code>empty-startup-checks-status</code> attribute. If the attribute is
<code>UP</code> (by default), the server can be ready when there are no startup checks in the deployments. Setting the <code>empty-startup-checks-status</code> attribute to <code>DOWN</code> will make this procedure fail when there are no readiness checks in the deployments.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If a deployment does not provide any startup checks, WildFly will automatically add one for each deployment (named <code>started-&lt;deployment name&gt;</code>) which always returns <code>UP</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This allows applications that does not provide startup checks to still be able to inform cloud containers when they are started to proceed with the container start.
Setting <code>empty-startup-checks-status</code> to <code>DOWN</code> ensures that the server will not be ready until the application is deployed. At that time, the <code>started-&lt;deployment name&gt;</code>
will be added (which returns <code>UP</code>) and the <code>empty-startup-checks</code> procedure will no longer be checked as there is now a startup check procedure provided either by the deployment or by the server.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="disabling-default-server-procedures"><a class="anchor" href="#disabling-default-server-procedures"></a><a class="link" href="#disabling-default-server-procedures">Disabling Default Server Procedures</a></h5>
<div class="paragraph">
<p>It is possible to disable all these server procedures by using the MicroProfile Config property <code>mp.health.disable-default-procedures</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The MicroProfile Config property <code>mp.health.disable-default-procedures</code> is read at 2 different times:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><em>When the server starts</em>, to determine if its server procedures should be disabled or enabled. It can be set using the system property <code>mp.health.disable-default-procedures</code> or the environment variable <code>MP_HEALTH_DISABLE_DEFAULT_PROCEDURES</code>. Setting this property in a deployment is ignored at that time.</p>
</li>
<li>
<p><em>When an application is deployed</em>, to determine if WildFly should add a readiness check if the deployment does not provide any. At that time, setting this property in a <code>microprofile-config.properties</code> file in the deployment would be taken into account. (with the usual priority rules for MicroProfile Config properties).</p>
</li>
</ol>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>When the <code>mp.health.disable-default-procedures</code> is set to <code>true</code> the server will not return any of its health checks in the responses which involve also the default empty configurable checks included before the deployments are processed, namely <code>empty-readiness-checks</code>, <code>empty-startup-checks</code>, and <code>empty-liveness-checks</code>. This means that the server might prematurely respond with invalid <code>UP</code> response particularly to <code>startup</code> and <code>readiness</code> invocations before the user deployment is processed. For this reason, MicroProfile Health specification defines two MicroProfile Config properties that specify the response returned while the server is still processing deployments, i.e. it returns an empty health response:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>mp.health.default.readiness.empty.response</code> (default <code>DOWN</code>) that specifies empty readiness response. This response will be switched to <code>UP</code> once the user deployment is processed even if it doesn&#8217;t contain any readiness checks. Otherwise, it will be switched to the status set by the user readiness checks.</p>
</li>
<li>
<p><code>mp.health.default.startup.empty.response</code> (default <code>DOWN</code>) that specifies empty startup response. This response will be switched to <code>UP</code> once the user deployment is processed even if it doesn&#8217;t contain any startup checks. Otherwise, it will be switched to the status set by the user startup checks.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-4"><a class="anchor" href="#component-reference-4"></a><a class="link" href="#component-reference-4">7.15.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile Health implementation is provided by the SmallRye Health project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-health">MicroProfile Health</a></p>
</li>
<li>
<p><a href="http://github.com/smallrye/smallrye-health/">SmallRye Health</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_JWT_SmallRye"><a class="anchor" href="#MicroProfile_JWT_SmallRye"></a><a class="link" href="#MicroProfile_JWT_SmallRye">7.16. MicroProfile JWT Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-jwt-auth">MicroProfile JWT RBAC</a> is provided by the <em>microprofile-jwt-smallrye</em> subsystem.</p>
</div>
<div class="paragraph">
<p>The MicroProfile JWT specification describes how authentication can be performed using cryptographically signed JWT tokens and the contents of the token to be used to establish a resuting identity without relying on access to external repositories of identities such as databases or directory servers.</p>
</div>
<div class="sect3">
<h4 id="subsystem-configuration-microprofile-jwt-smallrye"><a class="anchor" href="#subsystem-configuration-microprofile-jwt-smallrye"></a><a class="link" href="#subsystem-configuration-microprofile-jwt-smallrye">7.16.1. Subsystem</a></h4>
<div class="paragraph">
<p>The MicroProfile JWT integration is provided by the <em>microprofile-jwt-smallrye</em> subsystem and is included in the default configuration, if not present the subsystem can be added using the following CLI commands.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.jwt-smallrye:add

[standalone@localhost:9990 /] /subsystem=microprofile-jwt-smallrye:add</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point the server would need to be reloaded to activate the change.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuration-3"><a class="anchor" href="#configuration-3"></a><a class="link" href="#configuration-3">7.16.2. Configuration</a></h4>
<div class="paragraph">
<p>The <em>microprofile-jwt-smallrye</em> subsystem contains no configurable attributes or resources, it&#8217;s presence is required however to detect if a deployment is making use of the MP-JWT authentication mechanism and to activate support for JWT making use of the <a href="https://github.com/smallrye/smallrye-jwt">SmallRye JWT</a> project.</p>
</div>
<div class="sect4">
<h5 id="activation"><a class="anchor" href="#activation"></a><a class="link" href="#activation">Activation</a></h5>
<div class="paragraph">
<p>The subsystem will scan all deployments to detect if the <em>MP-JWT</em> mechanism is required for any web components and if true activate the integration and the authentication mechanism.</p>
</div>
<div class="paragraph">
<p>The classes in the deployment will be scanned to identify if there is a class which extends <code>jakarta.ws.rs.core.Application</code> annotated with the <code>org.eclipse.microprofile.auth.LoginConfig</code> to specify an <em>auth-method</em>.  Additionally the <em>auth-method</em> contained within the deployments <em>web.xml</em> will be checked.</p>
</div>
<div class="paragraph">
<p>If authentication configuration is defined within the <code>@LoginConfig</code> annotation and within the <em>web.xml</em> deployment descriptor the contents of the web.xml are given precedence.</p>
</div>
<div class="paragraph">
<p>If after evaluating the deployment the resulting <em>auth-method</em> is <em>MP-JWT</em> then this integration will be activated, in all other cases no activation will occur and deployment will continue as normal.</p>
</div>
</div>
<div class="sect4">
<h5 id="microprofile-config"><a class="anchor" href="#microprofile-config"></a><a class="link" href="#microprofile-config">MicroProfile Config</a></h5>
<div class="paragraph">
<p>For an individual deployment the configuration in relation to MicroProfile JWT can be provided using MicroProfile Config properties, many are defined within the MicroProfile JWT specification however SmallRye JWT also supports some additional properties.</p>
</div>
<div class="sect5">
<h6 id="microprofile-jwt-properties"><a class="anchor" href="#microprofile-jwt-properties"></a><a class="link" href="#microprofile-jwt-properties">MicroProfile JWT properties</a></h6>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 12.5%;">
<col style="width: 62.5%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Property Name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.verify.publickey</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Public Key supplied as a string, parsed from it in the order defined in section <a href="https://smallrye.io/docs/smallrye-jwt/configuration.html#_supported_public_key_formats">Supported Public Key Formats</a>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.verify.publickey.location</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Config property allows for an external or internal location of Public Key to be specified.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.verify.publickey.algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>RS256</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signature algorithm. Set it to <code>ES256</code> to support the Elliptic Curve signature algorithm.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.decrypt.key.location</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Config property allows for an external or internal location of Private Decryption Key to be specified.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.verify.issuer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Expected value of the JWT <code>iss</code> (issuer) claim.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.verify.audiences</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>none</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Comma separated list of the audiences that a token <code>aud</code> claim may contain.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.token.header</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Authorization</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property if another header such as <code>Cookie</code> is used to pass the token.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.jwt.token.cookie</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Bearer</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the cookie containing a token. This property will be effective only if  <code>mp.jwt.token.header</code> is set to <code>Cookie</code>.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>A minimal <code>microprofile-config.properties</code> could look like: -</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>mp.jwt.verify.publickey.location=META-INF/public.pem
mp.jwt.verify.issuer=quickstart-jwt-issuer</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="unavailable-options"><a class="anchor" href="#unavailable-options"></a><a class="link" href="#unavailable-options">Unavailable Options</a></h6>
<div class="paragraph">
<p>There are presently a couple of limitations with support for JWKS which we are looking to address.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If a JWKS is inlined using the <code>mp.jwt.verify.publickey</code> property then only the first key from the set will be used with the remainder being ignored.</p>
</li>
<li>
<p>Encoding of JWKS using Base64 is presently unsupported.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In both cases a clear text JWKS can be referenced instead using the <code>mp.jwt.verify.publickey.location</code> config property.</p>
</div>
<div class="paragraph">
<p>Support for Base64 encoded JWKS keys and inlined JWKS keys within the <code>mp.jwt.verify.publickey</code> property will be further evaluation and either support added or a contibution to the specification to remove these options.</p>
</div>
</div>
<div class="sect5">
<h6 id="smallrye-jwt-properties"><a class="anchor" href="#smallrye-jwt-properties"></a><a class="link" href="#smallrye-jwt-properties">SmallRye JWT Properties</a></h6>
<div class="paragraph">
<p>The SmallRye JWT specific properties allow for a lot of customisation not covered by the specification, however as these are not specification defined they could be subject to change.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 12.5%;">
<col style="width: 62.5%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Property Name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.key.location</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">NONE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Location of the verification key which can point to both public and secret keys. Secret keys can only be in the JWK format. Note that 'mp.jwt.verify.publickey.location' will be ignored if this property is set.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>RS256</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Signature algorithm. Set it to <code>ES256</code> to support the Elliptic Curve signature algorithm. This property is deprecated, use <code>mp.jwt.verify.publickey.algorithm</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.key-format</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ANY</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property to a specific key format such as <code>PEM_KEY</code>, <code>PEM_CERTIFICATE</code>, <code>JWK</code> or <code>JWK_BASE64URL</code> to optimize the way the verification key is loaded.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.relax-key-validation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Relax the validation of the verification keys, setting this property to <code>true</code> will allow public RSA keys with the length less than 2048 bit.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.certificate-thumbprint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If this property is enabled then a signed token must contain either 'x5t' or 'x5t#S256' X509Certificate thumbprint headers. Verification keys can only be in JWK or PEM Certificate key formats in this case. JWK keys must have a 'x5c' (Base64-encoded X509Certificate) property set.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.token.header</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Authorization</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property if another header such as <code>Cookie</code> is used to pass the token. This property is deprecated, use <code>mp.jwt.token.header</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.token.cookie</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the cookie containing a token. This property will be effective only if  <code>smallrye.jwt.token.header</code> is set to <code>Cookie</code>. This property is deprecated, use <code>mp.jwt.token.cookie</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.always-check-authorization</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property to <code>true</code> for <code>Authorization</code> header be checked even if the <code>smallrye.jwt.token.header</code> is set to <code>Cookie</code> but no cookie with a <code>smallrye.jwt.token.cookie</code> name exists.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.token.schemes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>Bearer</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Comma-separated list containing an alternative single or multiple schemes, for example, <code>DPoP</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.token.kid</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Key identifier. If it is set then the verification JWK key as well every JWT token must have a matching <code>kid</code> header.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.time-to-live</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of seconds that a JWT may be issued for use. Effectively, the difference between the expiration date of the JWT and the issued at date must not exceed this value.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.require.named-principal</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If an application relies on <code>java.security.Principal</code> returning a name then a token must have a <code>upn</code> or <code>preferred_username</code> or <code>sub</code> claim set. Setting this property will result in SmallRye JWT throwing an exception if none of these claims is available for the application code to reliably deal with a non-null <code>Principal</code> name.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.path.sub</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path to the claim containing the subject name. It starts from the top level JSON object and can contain multiple segments where each segment represents a JSON object name only, example: <code>realms/subject</code>. This property can be used if a token has no 'sub' claim but has the subject set in a different claim. Use double quotes with the namespace qualified claims.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.claims.sub</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This property can be used to set a default sub claim value when the current token has no standard or custom <code>sub</code> claim available. Effectively this property can be used to customize <code>java.security.Principal</code> name if no <code>upn</code> or <code>preferred_username</code> or <code>sub</code> claim is set.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.path.groups</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path to the claim containing the groups. It starts from the top level JSON object and can contain multiple segments where each segment represents a JSON object name only, example: <code>realm/groups</code>. This property can be used if a token has no 'groups' claim but has the groups set in a different claim. Use double quotes with the namespace qualified claims.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.groups-separator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">' '</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Separator for splitting a string which may contain multiple group values. It will only be used if the <code>smallrye.jwt.path.groups</code> property points to a custom claim whose value is a string. The default value is a single space because a standard OAuth2 <code>scope</code> claim may contain a space separated sequence.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.claims.groups</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This property can be used to set a default groups claim value when the current token has no standard or custom groups claim available.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.jwks.refresh-interval</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">60</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">JWK cache refresh interval in minutes. It will be ignored unless the <code>mp.jwt.verify.publickey.location</code> points to the HTTP or HTTPS URL based JWK set and no HTTP <code>Cache-Control</code> response header with a positive <code>max-age</code> parameter value is returned from a JWK set endpoint.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.jwks.forced-refresh-interval</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Forced JWK cache refresh interval in minutes which is used to restrict the frequency of the forced refresh attempts which may happen when the token verification fails due to the cache having no JWK key with a <code>kid</code> property matching the current token&#8217;s <code>kid</code> header. It will be ignored unless the <code>mp.jwt.verify.publickey.location</code> points to the HTTP or HTTPS URL based JWK set.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.expiration.grace</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">60</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Expiration grace in seconds. By default an expired token will still be accepted if the current time is no more than 1 min after the token expiry time.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.verify.aud</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Comma separated list of the audiences that a token <code>aud</code> claim may contain. This property is deprecated. Use <code>mp.jwt.verify.audiences</code> instead.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.required.claims</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Comma separated list of the claims that a token must contain.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.decrypt.key.location</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Config property allows for an external or internal location of Private Decryption Key to be specified. This property is deprecated, use <code>mp.jwt.decrypt.key.location</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.decrypt.algorithm</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>RSA_OAEP</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decryption algorithm.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">smallrye.jwt.token.decryption.kid</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Decryption Key identifier. If it is set then the decryption JWK key as well every JWT token must have a matching <code>kid</code> header.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="virtual-security"><a class="anchor" href="#virtual-security"></a><a class="link" href="#virtual-security">7.16.3. Virtual Security</a></h4>
<div class="paragraph">
<p>For traditional deployments to WildFly where security is required a security domain name would be identified during deployment and this in turn would be mapped to use configured resources either within the <em>elytron</em> or legacy <em>security</em> subsystems.</p>
</div>
<div class="paragraph">
<p>One of the main motivations for using MicroProfile JWT is the ability to describe an identity from the incoming token without relying on access to external resources.  For this reason MicroProfile JWT deployments will not depend on managed <code>SecurityDomain</code> resources, instead a virtual <code>SecurityDomain</code> will be created and used across the deployment.</p>
</div>
<div class="paragraph">
<p>As the deployment is configured entirely within the MicroProfile Config properties other than the presence of the <em>microprofile-jwt-smallrye</em> subsystem the virtual <code>SecurityDomain</code> means no other managed configuration is required for the deployment.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Metrics_SmallRye_Subsystem_Config"><a class="anchor" href="#MicroProfile_Metrics_SmallRye_Subsystem_Config"></a><a class="link" href="#MicroProfile_Metrics_SmallRye_Subsystem_Config">7.17. MicroProfile Metrics Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-metrics">MicroProfile Metrics</a> is provided by
 the <em>microprofile-metrics-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-metrics-smallrye"><a class="anchor" href="#required-extension-microprofile-metrics-smallrye"></a><a class="link" href="#required-extension-microprofile-metrics-smallrye">7.17.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is included in the standalone-microprofile configurations included in the
WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can add the extension to a configuration without it either by using the following CLI operations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.metrics-smallrye:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}

[standalone@localhost:9990 /] /subsystem=microprofile-metrics-smallrye:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}

[standalone@localhost:9990 /] reload</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or by adding an element to the application server profile XML to <code>&lt;extensions&gt;</code> section:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.wildfly.extension.microprofile.metrics-smallrye</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>and then the subsystem in the <code>&lt;profile&gt;</code> section:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-metrics-smallrye:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>It depends on the base metrics extension <code>org.wildfly.extension.metrics</code> that must be installed.</p>
</div>
</div>
<div class="sect3">
<h4 id="management-model-4"><a class="anchor" href="#management-model-4"></a><a class="link" href="#management-model-4">7.17.2. Management Model</a></h4>
<div class="paragraph">
<p>The <code>/subsystem=microprofile-metrics-smallrye</code> resource defines two attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>exposed-subsystems</code> - a list of strings corresponding to the names of subsystems that exposes their metrics in the HTTP metrics endpoints.
By default, it is not defined (there will be no metrics exposed by subsystem. The special wildcard "*" can be used to expose metrics from <em>all</em> subsystems. The standalone
configuration sets this attribute to "*".</p>
</li>
<li>
<p><code>prefix</code> - A string to prepend to WildFly metrics that are exposed by the HTTP endpoint <code>/metrics</code> with the Prometheus output format.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="http-endpoint"><a class="anchor" href="#http-endpoint"></a><a class="link" href="#http-endpoint">7.17.3. HTTP Endpoint</a></h4>
<div class="paragraph">
<p>The Metric HTTP endpoint is accessible on WildFly HTTP management interface <a href="http://localhost:9990/metrics">http://localhost:9990/metrics</a>.</p>
</div>
<div class="paragraph">
<p>Secured access to the HTTP endpoint is controlled by the <code>security-enabled</code> attribute of the <code>/subsystem=microprofile-metrics-smallrye</code> resource.
The value of this attribute will override the <code>security-enabled</code> attribute of the <code>/subsystem=metrics</code> resource (documented in <a href="#metrics-metrics-http-endpoint">Metrics subsystem configuration guide</a>).</p>
</div>
<div class="paragraph">
<p>When the <code>microprofile.metrics-smallrye</code> is installed, this HTTP endpoint will return metrics according to MicroProfile Metrics specification.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ curl -v http://localhost:9990/metrics
&lt; HTTP/1.1 200 OK
...
# HELP base:classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution
.
# TYPE base:classloader_total_loaded_class_count counter
base:classloader_total_loaded_class_count 10822.0
...</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="exposed-metrics-3"><a class="anchor" href="#exposed-metrics-3"></a><a class="link" href="#exposed-metrics-3">7.17.4. Exposed Metrics</a></h4>
<div class="paragraph">
<p>The HTTP endpoint exposes the following metrics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Base metrics - Required metrics specified in the MicroProfile 1.1 specification are exposed in the <code>base</code>  scope.</p>
</li>
<li>
<p>Vendor metrics - Vendor-specific metrics (e.g. for memory pools)</p>
</li>
<li>
<p>Application metrics - Metrics from the application and from the deployment&#8217;s subsystems are exposed in the <code>application</code> scope.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The WildFly metrics (that measures activity in the subsystem or application deployments) are exposed only on the <code>/metrics</code>
endpoint with the Prometheus format.</p>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-5"><a class="anchor" href="#component-reference-5"></a><a class="link" href="#component-reference-5">7.17.5. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile Metrics implementation is provided by the SmallRye Metrics project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-metrics">MicroProfile Metrics</a></p>
</li>
<li>
<p><a href="http://github.com/smallrye/smallrye-metrics/">SmallRye Metrics</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_OpenAPI_SmallRye"><a class="anchor" href="#MicroProfile_OpenAPI_SmallRye"></a><a class="link" href="#MicroProfile_OpenAPI_SmallRye">7.18. MicroProfile OpenAPI Subsystem Configuration</a></h3>
<div class="paragraph">
<p>The <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md">OpenAPI specification</a> defines a contract for JAX-RS applications in the same way that WSDL defined a contract for legacy web services.
The <a href="https://download.eclipse.org/microprofile/microprofile-open-api-1.1.2/microprofile-openapi-spec.html">MicroProfile OpenAPI specification</a> defines a mechanism for generating an OpenAPI v3 document from a JAX-RS application as well as an API for customizing production of the document.</p>
</div>
<div class="sect3">
<h4 id="subsystem"><a class="anchor" href="#subsystem"></a><a class="link" href="#subsystem">7.18.1. Subsystem</a></h4>
<div class="paragraph">
<p>The MicroProfile OpenAPI capability is provided by the microprofile-openapi-smallrye subsystem.
This subsystem is included in the default standalone-microprofile.xml configuration of the WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can also add the subsystem manually to any profile via the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()

[standalone@localhost:9990 /] /subsystem=microprofile-openapi-smallrye:add()</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuration-4"><a class="anchor" href="#configuration-4"></a><a class="link" href="#configuration-4">7.18.2. Configuration</a></h4>
<div class="paragraph">
<p>The microprofile-openapi-smallrye subsystem obtains all of its configuration via MicroProfile Config.  Thus the subsystem itself defines no attributes.</p>
</div>
<div class="paragraph">
<p>In addition to the <a href="https://download.eclipse.org/microprofile/microprofile-open-api-1.1.2/microprofile-openapi-spec.html#_core_configurations">standard Open API configuration</a> properties, WildFly supports the following additional MicroProfile Config properties:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 12.5%;">
<col style="width: 62.5%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property</th>
<th class="tableblock halign-left valign-top">Default</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.openapi.extensions.enabled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables/disables registration of an OpenAPI endpoint.  Many users will want to parameterize this to selectively enable/disable OpenAPI in different environments.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.openapi.extensions.path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/openapi</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Used to customize the path of the OpenAPI endpoint.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mp.openapi.extensions.servers.relative</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates whether auto-generated Server records are absolute or relative to the location of the OpenAPI endpoint.  If absolute, WildFly will generate Server records including the protocols, hosts, and ports at which the given deployment is accessible.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>e.g. <code>/META-INF/microprofile-config.properties</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>mp.openapi.extensions.enabled=${microprofile.openapi.enabled}
mp.openapi.extensions.path=/swagger
mp.openapi.extensions.servers.relative=false</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="https-endpoint"><a class="anchor" href="#https-endpoint"></a><a class="link" href="#https-endpoint">7.18.3. HTTP/S Endpoint</a></h4>
<div class="paragraph">
<p>The MicroProfile OpenAPI specification defines an HTTP endpoint that serves an OpenAPI 3.0 document describing the REST endpoints for the host.
The OpenAPI endpoint is registered using the configured path (e.g. <a href="http://localhost:8080/openapi" class="bare">http://localhost:8080/openapi</a>) local to the root of the host associated with a given deployment.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Currently, the OpenAPI endpoint for a given virtual host can only document a single JAX-RS deployment.
To use OpenAPI with multiple JAX-RS deployments registered with different context paths on the same virtual host, each deployment should use a distinct endpoint path.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>By default, the OpenAPI endpoint returns a YAML document.
Alternatively, a JSON document can be requested via an <code>Accept</code> HTTP header, or a <code>format</code> query parameter.</p>
</div>
<div class="paragraph">
<p>e.g.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="shell">$ curl -v http://localhost:8080/openapi?format=JSON
&lt; HTTP/1.1 200 OK
...
{&quot;openapi&quot;: &quot;3.0.1&quot; ... }


$ curl -v -H'Accept: application/json' http://localhost:8080/openapi
&lt; HTTP/1.1 200 OK
...
{&quot;openapi&quot;: &quot;3.0.1&quot; ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the Undertow server/host of a given application defines an HTTPS listener, then the OpenAPI document will also be available via HTTPS, e.g. <a href="https://localhost:8443/openapi" class="bare">https://localhost:8443/openapi</a></p>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-6"><a class="anchor" href="#component-reference-6"></a><a class="link" href="#component-reference-6">7.18.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile OpenAPI implementation is provided by the SmallRye OpenAPI project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-open-api">MicroProfile OpenAPI</a></p>
</li>
<li>
<p><a href="http://github.com/smallrye/smallrye-open-api/">SmallRye OpenAPI</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
References in this document to Java API for RESTful Web Services(JAX-RS) refer to Jakarta RESTful Web Services unless otherwise noted.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_OpenTracing_SmallRye"><a class="anchor" href="#MicroProfile_OpenTracing_SmallRye"></a><a class="link" href="#MicroProfile_OpenTracing_SmallRye">7.19. MicroProfile OpenTracing Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-opentracing">MicroProfile OpenTracing</a> is
provided as a Tech Preview feature by the <em>microprofile-opentracing-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-opentracing-smallrye"><a class="anchor" href="#required-extension-microprofile-opentracing-smallrye"></a><a class="link" href="#required-extension-microprofile-opentracing-smallrye">7.19.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is included in the standard configurations included in the WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can also add the extension to a configuration without it either by adding
an <code>&lt;extension module="org.wildfly.extension.microprofile.opentracing-smallrye"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.opentracing-smallrye:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}

[standalone@localhost:9990 /] /subsystem=microprofile-opentracing-smallrye:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="supported-instrumentation-libraries"><a class="anchor" href="#supported-instrumentation-libraries"></a><a class="link" href="#supported-instrumentation-libraries">7.19.2. Supported instrumentation libraries</a></h4>
<div class="paragraph">
<p>WildFly&#8217;s MicroProfile OpenTracing subsystem implements MicroProfile 1.3, which includes support for tracing Jakarta RESTful Web Services and Jakarta Contexts and Dependency Injection.</p>
</div>
<div class="paragraph">
<p>Currently the subsystem allows the configuration of <a href="https://github.com/jaegertracing/jaeger-client-java">Jaeger Java Client</a>. You can then specify which tracer to use in your deployment by specifying a <code>smallrye.opentracing.tracer.configuration</code> init-parameter in your deployment descriptor. If this value is wrong the deployment will fail.
You can also set the default tracer to be injected by using the <code>default-tracer</code> attribute on the subsystem configuration.</p>
</div>
<div class="paragraph">
<p>Additionally, applications being deployed are able to provide their own tracers via the
<a href="https://github.com/opentracing-contrib/java-tracerresolver"><code>TracerResolver</code></a> facility. In that case, the default tracer will <strong>not</strong> be used.</p>
</div>
<div class="paragraph">
<p>For compatibility if no tracer is defined in the subsystem and no tracer can be resolved, then a Jaeger Tracer instance will be created from the environment variables.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-a-jaeger-tracer"><a class="anchor" href="#configuring-a-jaeger-tracer"></a><a class="link" href="#configuring-a-jaeger-tracer">7.19.3. Configuring a Jaeger tracer</a></h4>
<div class="paragraph">
<p>To add a new Jaeger tracer instance you can use the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=microprofile-opentracing-smallrye/jaeger-tracer=my-tracer:add()
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Those are the configuration attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>propagation</code>: The supported trace context propagation formats:</p>
<div class="ulist">
<ul>
<li>
<p>JAEGER: The default Jaeger trace context propagation format.</p>
</li>
<li>
<p>B3: The Zipkin B3 trace context propagation format.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>sampler-type</code>: The type of sampler to use in the tracer. Optional. Valid values: remote (default),ratelimiting, probabilistic, const.</p>
</li>
<li>
<p><code>sampler-param</code>: The floating point value that makes sense for the correct samplerType.</p>
</li>
<li>
<p><code>sampler-manager-host-port</code>: the port of the sampling manager that can provide sampling strategy to this service.</p>
</li>
<li>
<p><code>sender-binding</code>: The outbound socket binding to connecto the Agent.</p>
</li>
<li>
<p><code>sender-endpoint</code>: The endpoint, like <a href="https://jaeger-collector:14268/api/traces" class="bare">https://jaeger-collector:14268/api/traces</a></p>
</li>
<li>
<p><code>sender-user</code>: The Basic Auth username to be added on Authorization headers for requests sent to the endpoint.</p>
</li>
<li>
<p><code>sender-auth-password</code>: The Basic Auth password to be added on Authorization headers for requests sent to the endpoint.</p>
</li>
<li>
<p><code>sender-auth-token</code>: The Auth Token to be added as "Bearer" on Authorization headers for requests sent to the endpoint.</p>
</li>
<li>
<p><code>reporter-log-spans</code>: Boolean to indicates whether the reporter should log the spans.</p>
</li>
<li>
<p><code>reporter-flush-interval</code>: The flush interval when reporting spans remotely in milliseconds.</p>
</li>
<li>
<p><code>reporter-max-queue-size</code>: The reporter&#8217;s maximum queue size.</p>
</li>
<li>
<p><code>tracer_id_128bit</code>: Opt-in to use 128 bit traceIds. By default, uses 64 bits.</p>
</li>
<li>
<p><code>tracer-tags</code>: A comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default, the service name used with the Jaeger Client is derived from the deployment&#8217;s name, which is usually the WAR file name.</p>
</div>
<div class="paragraph">
<p>As defined by the MicroProfile OpenTracing specification, Jakarta Contexts and Dependency Injection beans are traced if the annotation
<code>org.eclipse.microprofile.opentracing.Traced</code> is present, either at the type or method level. Tracing can be disabled
by setting the annotation&#8217;s value to <code>false</code>. Similarly, a custom operation name can be set by specifying the parameter
<code>operationName</code> for that annotation. The semantics are ruled by the MicroProfile OpenTracing specification.</p>
</div>
<div class="paragraph">
<p>Note that Jakarta Contexts and Dependency Injection support for the deployment is required in order to activate the MicroProfile OpenTracing support. A simple
Jakarta RESTful Web Services application with no Jakarta Contexts and Dependency Injection support will <strong>not</strong> be traced.</p>
</div>
<div class="paragraph">
<p>Managed beans with multiple facets, such as Jakarta Enterprise Beans, can also be traced by annotating them with <code>@Traced</code>, but with
limitations. For instance, asynchronous invocations will yield a new trace, instead of having the span to join an
existing trace.</p>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-7"><a class="anchor" href="#component-reference-7"></a><a class="link" href="#component-reference-7">7.19.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile OpenTracing implementation is provided by the SmallRye OpenTracing project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-opentracing">MicroProfile OpenTracing</a></p>
</li>
<li>
<p><a href="https://github.com/smallrye/smallrye-opentracing/">SmallRye OpenTracing</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile-Fault-Tolerance-SmallRye"><a class="anchor" href="#MicroProfile-Fault-Tolerance-SmallRye"></a><a class="link" href="#MicroProfile-Fault-Tolerance-SmallRye">7.20. MicroProfile Fault Tolerance Subsystem</a></h3>
<div class="sect3">
<h4 id="specification"><a class="anchor" href="#specification"></a><a class="link" href="#specification">7.20.1. Specification</a></h4>
<div class="paragraph">
<p>WildFly&#8217;s MicroProfile Fault Tolerance subsystem implements MicroProfile Fault Tolerance 4.0.</p>
</div>
<div class="paragraph">
<p>This MicroProfile specification provides the following interceptor bindings:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>@Timeout</code> to define a maximum duration or an execution.</p>
</li>
<li>
<p><code>@Retry</code> to attempt execution again in case of a failure.</p>
</li>
<li>
<p><code>@Fallback</code>  to provide an alternative execution in case of a prior failure.</p>
</li>
<li>
<p><code>@CircuitBreaker</code> to automatically fail-fast when an execution repeatedly fails.</p>
</li>
<li>
<p><code>@Bulkhead</code> to limit concurrent executions so that one method doesn&#8217;t overload the entire system.</p>
</li>
<li>
<p><code>@Asynchronous</code> to execute a method asynchronously.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For complete documentation please refer to MicroProfile Fault Tolerance 4.0 <a href="https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0/microprofile-fault-tolerance-spec-4.0.html">specification</a>.</p>
</div>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-fault-tolerance">MicroProfile Fault Tolerance</a> is
provided as by the <code>microprofile-fault-tolerance-smallrye</code> subsystem.</p>
</div>
<div class="paragraph">
<p>The MicroProfile Fault Tolerance implementation is provided by the <a href="https://github.com/smallrye/smallrye-fault-tolerance">SmallRye Fault Tolerance</a> project.</p>
</div>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-fault-tolerance-smallrye"><a class="anchor" href="#required-extension-microprofile-fault-tolerance-smallrye"></a><a class="link" href="#required-extension-microprofile-fault-tolerance-smallrye">7.20.2. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is automatically included in the <code>standalone-microprofile</code> server profiles,
however, it is not included by default in the default configuration of WildFly.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The MicroProfile Metrics extension and subsystem are required by this extension,
please follow the instructions in the <a href="#required-extension-microprofile-metrics-smallrye">MicroProfile Metrics Subsystem Configuration section</a>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can add the extension to a configuration without it either by using the following CLI operations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.fault-tolerance-smallrye:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}

[standalone@localhost:9990 /] /subsystem=microprofile-fault-tolerance-smallrye:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}
[standalone@localhost:9990 /] reload</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or by adding an element to the application server profile XML to <code>&lt;extensions&gt;</code> section:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.wildfly.extension.microprofile.fault-tolerance-smallrye</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>and then the subsystem in the <code>&lt;profile&gt;</code> section:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:microprofile-fault-tolerance-smallrye:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The subsystem itself does not have any configurable elements.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuration-5"><a class="anchor" href="#configuration-5"></a><a class="link" href="#configuration-5">7.20.3. Configuration</a></h4>
<div class="paragraph">
<p>Apart from configuration properties defined by the specification, the SmallRye implementation provides the following
configuration properties:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 3. SmallRye Fault Tolerance configuration properties</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Default</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>io.smallrye.faulttolerance.mainThreadPoolSize</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>100</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of threads in the thread pool.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>io.smallrye.faulttolerance.mainThreadPoolQueueSize</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-1</code> (unbounded)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Size of the queue that the thread pool should use.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Reactive_Streams_Operators_SmallRye"><a class="anchor" href="#MicroProfile_Reactive_Streams_Operators_SmallRye"></a><a class="link" href="#MicroProfile_Reactive_Streams_Operators_SmallRye">7.21. MicroProfile Reactive Streams Operators Subsystem Configuration</a></h3>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-reactive-streams">MicroProfile Reactive Streams Operators</a> is
provided as a Tech Preview feature by the <em>microprofile-reactive-streams-operators-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-reactive-streams-operators-smallrye"><a class="anchor" href="#required-extension-microprofile-reactive-streams-operators-smallrye"></a><a class="link" href="#required-extension-microprofile-reactive-streams-operators-smallrye">7.21.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is <strong>not</strong> included in the standard configurations included in the WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can add the extension to a configuration either by adding
an <code>&lt;extension module="org.wildfly.extension.microprofile.reactive-streams-operators-smallrye"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.reactive-streams-operators-smallrye:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}

[standalone@localhost:9990 /] /subsystem=microprofile-reactive-streams-operators-smallrye:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you provision your own server and include the <code>microprofile-reactive-streams-operators</code> layer, you will get the required modules, and the extension and subsystem will be added to your configuration.</p>
</div>
</div>
<div class="sect3">
<h4 id="specification-2"><a class="anchor" href="#specification-2"></a><a class="link" href="#specification-2">7.21.2. Specification</a></h4>
<div class="paragraph">
<p>WildFly&#8217;s MicroProfile Reactive Streams Operators subsystem implements MicroProfile Reactive Streams Operators 2.0, which adds support for asynchronous streaming of data. It essentially replicates the the interfaces, and their implementations, that were made available in the <a href="https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html">java.util.concurrent.Flow</a> class introduced in Java 9. Thus MicroProfile Reactive Streams Operators can be considered a stop-gap until Java 9 and later is ubiquitous.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuration-6"><a class="anchor" href="#configuration-6"></a><a class="link" href="#configuration-6">7.21.3. Configuration</a></h4>
<div class="paragraph">
<p>The <code>microprofile-reactive-streams-operators-smallrye</code> subsystem contains no configurable attributes or resources. Its presence makes the interfaces
from the MicroProfile Reactive Streams Operators available to a deployment, and provides the implementation. Additionally it makes an instance of the <a href="https://github.com/eclipse/microprofile-reactive-streams-operators/blob/master/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsEngine.java">ReactiveStreamsEngine</a> class available for injection.</p>
</div>
<div class="sect4">
<h5 id="activation-2"><a class="anchor" href="#activation-2"></a><a class="link" href="#activation-2">Activation</a></h5>
<div class="paragraph">
<p>If the subsystem is present, the MicroProfile Reactive Streams Operators functionality will be available for all deployments on the server.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-8"><a class="anchor" href="#component-reference-8"></a><a class="link" href="#component-reference-8">7.21.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile Reactive Streams Operators implementation is provided by the SmallRye Mutiny project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://microprofile.io/project/eclipse/microprofile-reactive-streams">MicroProfile Reactive Streams Operators</a></p>
</li>
<li>
<p><a href="https://github.com/smallrye/smallrye-mutiny">SmallRye Mutiny</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="MicroProfile_Reactive_Messaging_SmallRye"><a class="anchor" href="#MicroProfile_Reactive_Messaging_SmallRye"></a><a class="link" href="#MicroProfile_Reactive_Messaging_SmallRye">7.22. MicroProfile Reactive Messaging Subsystem Configuration</a></h3>
<div class="listingblock">
<div class="content">
<pre>:smallrye-reactive-messaging-version:       3.6
:smallrye-reactive-messaging-tag:           {smallrye-reactive-messaging-version}.0
:eclipse-mp-reactive-messaging-api-version: 2.0</pre>
</div>
</div>
<div class="paragraph">
<p>Support for <a href="https://microprofile.io/project/eclipse/microprofile-reactive-messaging">MicroProfile Reactive Messaging</a> is
provided as a Tech Preview feature by the <em>microprofile-reactive-messaging-smallrye</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="required-extension-microprofile-reactive-messaging-smallrye"><a class="anchor" href="#required-extension-microprofile-reactive-messaging-smallrye"></a><a class="link" href="#required-extension-microprofile-reactive-messaging-smallrye">7.22.1. Required Extension</a></h4>
<div class="paragraph">
<p>This extension is <strong>not</strong> included in the standard configurations included in the WildFly distribution.</p>
</div>
<div class="paragraph">
<p>You can add the extension to a configuration either by adding
an <code>&lt;extension module="org.wildfly.extension.microprofile.reactive-messaging-smallrye"/&gt;</code>
element to the xml or by using the following CLI operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.reactive-messaging-smallrye:add
{&quot;outcome&quot; =&gt; &quot;success&quot;}

[standalone@localhost:9990 /] /subsystem=microprofile-reactive-messaging-smallrye:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To use this subsystem, you must also enable the <a href="#MicroProfile_Reactive_Streams_Operators_SmallRye">MicroProfile Reactive Streams Operators</a> extension and subsystem.</p>
</div>
<div class="paragraph">
<p>If you provision your own server and include the <code>microprofile-reactive-messaging</code> Galleon layer, you will get the required modules, and the extension and subsystem will be added to your configuration.</p>
</div>
<div class="paragraph">
<p>If you provision the <code>microprofile-reactive-messaging-kafka</code> Galleon layer it includes the modules to enable the Kafka connector functionality. The <code>microprofile-reactive-messaging-kafka</code> layer includes the <code>microprofile-reactive-messaging</code> layer which provides the core MicroProfile Reactive Messaging functionality.</p>
</div>
</div>
<div class="sect3">
<h4 id="specification-3"><a class="anchor" href="#specification-3"></a><a class="link" href="#specification-3">7.22.2. Specification</a></h4>
<div class="paragraph">
<p>WildFly&#8217;s MicroProfile Reactive Messaging subsystem implements MicroProfile Reactive Messaging {eclipse-mp-reactive-messaging-api-version}, which adds support for asynchronous messaging support based on MicroProfile Reactive Streams Operators.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuration-7"><a class="anchor" href="#configuration-7"></a><a class="link" href="#configuration-7">7.22.3. Configuration</a></h4>
<div class="paragraph">
<p>The <code>microprofile-reactive-messaging-smallrye</code> subsystem contains no configurable attributes or resources. For the core MicroProfile Reactive Messaging functionality there is no configuration. For configuration of the <a href="#microprofile-reactive-messaging-smallrye-config-connectors">connectors</a> to external brokers MicroProfile Config is used.</p>
</div>
<div class="sect4">
<h5 id="activation-3"><a class="anchor" href="#activation-3"></a><a class="link" href="#activation-3">Activation</a></h5>
<div class="paragraph">
<p>The subsystem will scan all deployments to find classes containing methods with the <code>org.eclipse.microprofile.reactive.messaging.Incoming</code> or <code>org.eclipse.microprofile.reactive.messaging.Outgoing</code> annotations. If these annotations are found, Reactive Messaging will be enabled for the deployment.</p>
</div>
</div>
<div class="sect4">
<h5 id="programming-model-and-limitations"><a class="anchor" href="#programming-model-and-limitations"></a><a class="link" href="#programming-model-and-limitations">Programming model and Limitations</a></h5>
<div class="paragraph">
<p>See the spec for more thorough examples, this section just attempts to summarize the highlights.</p>
</div>
<div class="paragraph">
<p>Version 1.0 of the MicroProfile Reactive Messaging specification introduced the <code>@Incoming</code> and <code>@Outgoing</code> annotations. They are intended for use in an <code>@ApplicationScoped</code> (or <code>@Dependent</code>) CDI bean:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ApplicationScoped</span>
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyBean</span> {
    <span class="annotation">@Outgoing</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">in-memory</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">public</span> <span class="predefined-type">String</span> generate() {
        <span class="keyword">return</span> ...; <span class="comment">// Do some generation of values</span>
    }

    <span class="annotation">@Incoming</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">in-memory</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">public</span> <span class="type">void</span> consume(<span class="predefined-type">String</span> value) {
        <span class="predefined-type">System</span>.out.println(value);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Values generated by the <code>generate()</code> method will be received by the <code>consume()</code> method. In this basic setup where the channel names match, the streams are dealt with in-memory. We&#8217;ll see how to have them handled by Kafka later on.</p>
</div>
<div class="paragraph">
<p>In the above example, we are essentially generating values and consuming them with no user-interaction. MicroProfile Reactive Messaging 2.0 introduces a <code>@Channel</code> annotation, which can be used to inject a <code>Publisher</code> for receiving values sent on streams, and an <code>Emitter</code> which can be used to send values to a stream. This makes it easier to send/receive values from code paths resulting from user interaction:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ApplicationScoped</span>
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyBean</span> {
    <span class="annotation">@Inject</span>
    <span class="annotation">@Channel</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">in-memory</span><span class="delimiter">&quot;</span></span>)
    Emitter&lt;<span class="predefined-type">String</span>&gt; emitter;

    <span class="annotation">@Inject</span>
    <span class="annotation">@Channel</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">in-memory</span><span class="delimiter">&quot;</span></span>)
    Publisher&lt;<span class="predefined-type">String</span>&gt; publisher;

    <span class="type">void</span> send(<span class="predefined-type">String</span> value) {
        emitter.send(value);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above example we can now easily send data to the Reactive Messaging streams by calling <code>Emitter.send()</code>. Similarly, we can subscribe to the Publisher and receive the data. However, receiving still has a few shortcomings:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The above example will not work out of the box. When trying to send on the <code>Emitter</code>, you will get an error that there are no subscibers (which in turn runs the risk of causing overflow). This can be worked around by creating a subscription on the <code>Publisher</code>.</p>
</li>
<li>
<p>At present there can only be one subscription on the injected <code>Publisher</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The above points means that this <code>Publisher</code> is not usable directly as an asynchronous return value for e.g. a Jakarta RESTFul Webservices endpoint. As the Jakarta RESTFul Webservices request is what will create the subscription such a call would need to happen before calling <code>Emitter.send()</code>.</p>
</div>
<div class="paragraph">
<p>If we replace the <code>Emitter</code> with the <code>generate()</code> method from the original method our example will work. However, if we return the Publisher to more than one Jakarta RESTFul Webservices request, we end up with more than one subscriptions which will not all receive every single value.</p>
</div>
<div class="paragraph">
<p>User&#8217;s applications intended to return published values to users via e.g. Jakarta RESTFul Webservices will need to do their own subscriptions and buffering of the data. Care must be taken to not let the cache grow uncontrolled, which could cause OutOfMemoryErrors.</p>
</div>
</div>
<div class="sect4">
<h5 id="microprofile-reactive-messaging-smallrye-config-connectors"><a class="anchor" href="#microprofile-reactive-messaging-smallrye-config-connectors"></a><a class="link" href="#microprofile-reactive-messaging-smallrye-config-connectors">Connectors</a></h5>
<div class="paragraph">
<p>MicroProfile Reactive Messaging is designed to be flexible enough to integrate with a wide variety of external messaging systems. This functionality is provided via 'connectors'.</p>
</div>
<div class="paragraph">
<p>The only included connector at the moment is the Kafka connector.</p>
</div>
<div class="paragraph">
<p>Connectors are configured using MicroProfile Config. The property keys for the methods have some prefixes mandated by the MicroProfile Reactive Messaging Specification which lists these as:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>mp.messaging.incoming.[channel-name].[attribute]=[value]</code></p>
</li>
<li>
<p><code>mp.messaging.outgoing.[channel-name].[attribute]=[value]</code></p>
</li>
<li>
<p><code>mp.messaging.connector.[connector-name].[attribute]=[value]</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Essentially <code>channel-name</code> is the <code>@Incoming.value()</code> or the  <code>@Outgoing.value()</code>.</p>
</div>
<div class="paragraph">
<p>If we have the following pair of methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Outgoing</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">to</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">int</span> send() {
    <span class="type">int</span> i = <span class="comment">// Randomly generated...</span>
}

<span class="annotation">@Incoming</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">from</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">void</span> receive(<span class="type">int</span> i) {
    <span class="comment">// Process payload</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then the property prefixes mandated by the MicroProfile Reactive Messaging specifications are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>mp.messaging.incoming.from.</code> - this would pick out the property as configuration of the <code>receive()</code> method.</p>
</li>
<li>
<p><code>mp.messaging.outgoing.to.</code> - this would pick out the property as configuration of the <code>send()</code> method.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Note that although these prefixes are understood by the subsystem, the full set depends on the connector you want to configure. Different connectors understand different properties.</p>
</div>
<div class="sect5">
<h6 id="kafka-connector"><a class="anchor" href="#kafka-connector"></a><a class="link" href="#kafka-connector">Kafka Connector</a></h6>
<div class="paragraph">
<p>An example of a minimal <code>microprofile-config.properties</code> file for Kafka for the example application shown previously:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>kafka.bootstrap.servers=kafka:9092

mp.messaging.outgoing.to.connector=smallrye-kafka
mp.messaging.outgoing.to.topic=my-topic
mp.messaging.outgoing.to.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer

mp.messaging.incoming.from.connector=smallrye-kafka
mp.messaging.incoming.from.topic=my-topic
mp.messaging.incoming.from.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer</code></pre>
</div>
</div>
<div class="paragraph">
<p>Next we will briefly discuss each of these entries. Remember the <code>to</code> channel is on the <code>send()</code> method, and the <code>from</code> channel is on the <code>receive()</code> method.</p>
</div>
<div class="paragraph">
<p><code>kafka.bootstrap.servers=kafka:9092</code> sets the URL of the Kafka broker to connect to for the whole application. It could also be done for just the <code>to</code> channel by setting <code>mp.messaging.outgoing.to.bootstrap.servers=kafka:9092</code> instead.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.outgoing.to.connector=smallrye-kafka</code> says that we want to use Kafka to back the <code>to</code> channel. Note that the value <code>smallrye-kafka</code> is SmallRye Reactive Messaging specific, and will only be understood if the Kafka connector is enabled.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.outgoing.to.topic=my-topic</code> says that we will send data to the Kafka topic called <code>my-topic</code>.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.outgoing.to.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer</code> tells the connector to use <code>IntegerSerializer</code> to serialize the values output by the <code>send()</code> method when writing to the topic. Kafka provides serializers for the standard Java types. You may implement your own serializer by writing a class implementing <code>org.apache.kafka.common.serialization.Serializer</code> and including it in the deployment.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.incoming.from.connector=smallrye-kafka</code> says that we want to use Kafka to back the <code>from</code> channel. As above, the value <code>smallrye-kafka</code> is SmallRye Reactive Messaging specific.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.incoming.from.topic=my-topic</code> says that we will read data from the Kafka topic called <code>my-topic</code>.</p>
</div>
<div class="paragraph">
<p><code>mp.messaging.incoming.from.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer</code> tells the connector to use <code>IntegerDeserializer</code> to deserialize the values from the topic before calling the <code>receive()</code> method. You may implement your own deserializer by writing a class implementing <code>org.apache.kafka.common.serialization.Deserializer</code> and including it in the deployment.</p>
</div>
<div class="paragraph">
<p>In addition to the above, Apache Kafka, and SmallRye Reactive Messaging&#8217;s Kafka connector understand a lot more properties. These can be found in the SmallRye Reactive Messaging Kafka connector <a href="https://smallrye.io/smallrye-reactive-messaging/smallrye-reactive-messaging/{smallrye-reactive-messaging-version}/kafka/kafka.html">documentation</a>, and in the Apache Kafka documentation for the <a href="https://kafka.apache.org/documentation/#producerconfigs">producers</a> and the <a href="https://kafka.apache.org/documentation/#consumerconfigs">consumers</a>.</p>
</div>
<div class="paragraph">
<p>The prefixes discussed above are stripped off before passing the property to Kafka. The same happens for other configuration properties. See the Kafka documentation for more details about how to configure Kafka consumers and producers.</p>
</div>
<div class="sect6">
<h7 id="connecting-to-secure-kafka"><a class="anchor" href="#connecting-to-secure-kafka"></a><a class="link" href="#connecting-to-secure-kafka">Connecting to secure Kafka</a></h7>
<div class="paragraph">
<p>If connecting to a Kafka instance secured with SSL and SASL, the following example 'microprofile-config.properties' will help you get started. There are a few new properties. We are showing them on the connector level but they could equally well be defined on the channel level (i.e. with the <code>mp.messaging.outgoing.to-kafka.</code> and <code>mp.messaging.incoming.from-kafka.</code> prefixes from the previous examples rather than the connector-wide <code>mp.messaging.connector.smallrye-kafka</code> prefix).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>mp.messaging.connector.smallrye-kafka.bootstrap.servers=localhost:9092
mp.messaging.connector.smallrye-kafka.sasl.mechanism=PLAIN
mp.messaging.connector.smallrye-kafka.security.protocol=SASL_SSL
mp.messaging.connector.smallrye-kafka.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
  username=&quot;${USER}&quot; \
  password=&quot;${PASSWORD}&quot;;
mp.messaging.connector.smallrye-kafka.wildfly.elytron.ssl.context=test

# Channel configuration would follow here, but is left out for brevity</code></pre>
</div>
</div>
<div class="paragraph">
<p>Each of these lines has the following meaning:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>mp.messaging.connector.smallrye-kafka.bootstrap.servers=localhost:9092</code> - specifies the Kafka servers to connect to. This is the same as in the previous examples</p>
</li>
<li>
<p><code>mp.messaging.connector.smallrye-kafka.sasl.mechanism=PLAIN</code> - specifies the SASL mechanism to use. See <code>sasl.mechanism</code> in the Kafka documentation for other choices.</p>
</li>
<li>
<p><code>mp.messaging.connector.smallrye-kafka.security.protocol</code> - specifies the protocol mechanism to use. See <code>security.protocol</code> in the Kafka documentation for other choices. In this case we are using <code>SASL_SSL</code> which means that communication is over SSL, and that SASL is used to authenticate</p>
</li>
<li>
<p><code>mp.messaging.connector.smallrye-kafka.sasl.jaas.config=&#8230;&#8203;</code> - specifies how we will authenticate with Kafka. In order to not hardcode the credentials in our <code>microprofile-config.properties file</code> we are using the property substitution feature of MicroProfile Config. In this case, if you have defined the <code>USER</code> and <code>PASSWORD</code> environment variables they will be passed in as part of the configuration</p>
</li>
<li>
<p><code>mp.messaging.connector.smallrye-kafka.wildfly.elytron.ssl.context=test</code> - this is not needed if Kafka is secured with a CA signed certificate. If you are using self-signed certificates, you will need to specify a truststore in the Elytron subsystem, and create an <code>SSLContext</code> referencing that. The value of this property is used to look up the <code>SSLContext</code> in the Elytron subsystem under <code>/subsystem=elytron/client-ssl-context=*</code> in the WildFly management model. In this case the property value is <code>test</code>, so we look up the <code>SSLContext</code> defined by <code>/subsystem=elytron/client-ssl-context=test</code> and use that configure the truststore to use for the connection to Kafka.</p>
</li>
</ul>
</div>
</div>
<div class="sect6">
<h7 id="kafka-user-api"><a class="anchor" href="#kafka-user-api"></a><a class="link" href="#kafka-user-api">Kafka User API</a></h7>
<div class="paragraph">
<p>In order to be able to get more information about messages received from Kafka, and to be able to influence how Kafka handles messages, there is a user API for Kafka. This API lives in the <a href="https://github.com/smallrye/smallrye-reactive-messaging/tree/{smallrye-reactive-messaging-tag}/smallrye-reactive-messaging-kafka-api/src/main/java/io/smallrye/reactive/messaging/kafka/api"><code>io/smallrye/reactive/messaging/kafka/api</code></a> package.</p>
</div>
<div class="paragraph">
<p>The API consists of the following classes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/smallrye/smallrye-reactive-messaging/tree/{smallrye-reactive-messaging-tag}/smallrye-reactive-messaging-kafka-api/src/main/java/io/smallrye/reactive/messaging/kafka/api/IncomingKafkaRecordMetadata.java"><code>IncomingKafkaRecordMetadata</code></a> - This metadata contains information such as:</p>
<div class="ulist">
<ul>
<li>
<p>the <code>key</code> of the Kafka record represented by a <code>Message</code></p>
</li>
<li>
<p>the Kafka <code>topic</code> and <code>partition</code> used for the <code>Message</code>, and the <code>offset</code> within those</p>
</li>
<li>
<p>the <code>Message</code> <code>timestamp</code> and <code>timestampType</code></p>
</li>
<li>
<p>the <code>Message</code> <code>headers</code> - these are pieces of information the application can attach on the producing side, and receive on the consuming side. They are stored and forwarded on by Kafka but have no meaning to Kafka itself.</p>
</li>
</ul>
</div>
</li>
<li>
<p><a href="https://github.com/smallrye/smallrye-reactive-messaging/tree/{smallrye-reactive-messaging-tag}/smallrye-reactive-messaging-kafka-api/src/main/java/io/smallrye/reactive/messaging/kafka/api/OutgoingKafkaRecordMetadata.java"><code>OutgoingKafkaRecordMetadata</code></a> - This is constructed via the builder returned via the <code>builder()</code> method, and allows you to specify/override how Kafka will handle the messages. Similar to the <code>IncomingKafkaRecordMetadata</code> case, you can set:</p>
<div class="ulist">
<ul>
<li>
<p>the <code>key</code>. Kafka will then treat this entry as the key of the message</p>
</li>
<li>
<p>the <code>topic</code>, as already seen we typically use the <code>microprofile-config.properties</code> configuration to specify the topic to use for a channel backed by Kafka. However, in some cases the code sending the message might need to make some choices (for example depending on values contained in the data) about which topic to send to. Specifying this here will make Kafka use that topic.</p>
</li>
<li>
<p>the <code>partition</code>. Generally, it is best to let Kafka&#8217;s partitioner choose the partition, but for cases where it is essential to be able to specify it this can be done</p>
</li>
<li>
<p>the <code>timestamp</code> if you don&#8217;t want the one auto-generated by Kafka</p>
</li>
<li>
<p><code>headers</code> - you can attach headers for the consumer, as mentioned for <code>IncomingKafkaRecordMetadata</code></p>
</li>
</ul>
</div>
</li>
<li>
<p><a href="https://github.com/smallrye/smallrye-reactive-messaging/tree/{smallrye-reactive-messaging-tag}/smallrye-reactive-messaging-kafka-api/src/main/java/io/smallrye/reactive/messaging/kafka/api/KafkaMetadataUtil.java"><code>KafkaMetadataUtil</code></a> contains utility methods to write <code>OutgoingKafkaRecordMetadata</code> to a <code>Message</code>, and to read <code>IncomingKafkaRecordMetadata</code> from a <code>Message</code>. Note that if you write <code>OutgoingKafkaRecordMetadata</code> to a <code>Message</code> which is sent to a channel not handled by Kafka it will be ignored, and if you attempt to read <code>IncomingKafkaRecordMetadata</code> from a <code>Message</code> arriving from a channel no handled by Kafka it will be <code>null</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following example shows how to write and read the <code>key</code> from a message:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="annotation">@Inject</span>
<span class="annotation">@Channel</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">from-user</span><span class="delimiter">&quot;</span></span>)
Emitter&lt;<span class="predefined-type">Integer</span>&gt; emitter;

<span class="annotation">@Incoming</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">from-user</span><span class="delimiter">&quot;</span></span>)
<span class="annotation">@Outgoing</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">to-kafka</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> Message&lt;<span class="predefined-type">Integer</span>&gt; send(Message&lt;<span class="predefined-type">Integer</span>&gt; msg) {
    <span class="comment">// Set the key in the metadata</span>
    OutgoingKafkaRecordMetadata&lt;<span class="predefined-type">String</span>&gt; md =
            OutgoingKafkaRecordMetadata.&lt;<span class="predefined-type">String</span>&gt;builder()
                .withKey(<span class="string"><span class="delimiter">&quot;</span><span class="content">KEY-</span><span class="delimiter">&quot;</span></span> + i)
                .build();
    <span class="comment">// Note that Message is immutable so the copy returned by this method</span>
    <span class="comment">// call is not the same as the parameter to the method</span>
    <span class="keyword">return</span> KafkaMetadataUtil.writeOutgoingKafkaMetadata(msg, md);
}

<span class="annotation">@Incoming</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">from-kafka</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> CompletionStage&lt;<span class="predefined-type">Void</span>&gt; receive(Message&lt;<span class="predefined-type">Integer</span>&gt; msg) {
    IncomingKafkaRecordMetadata&lt;<span class="predefined-type">String</span>, <span class="predefined-type">Integer</span>&gt; metadata =
        KafkaMetadataUtil.readIncomingKafkaMetadata(msg).get();

    <span class="comment">// We can now read the Kafka record key</span>
    <span class="predefined-type">String</span> key = metadata.getKey();

    <span class="comment">// When using the Message wrapper around the payload we need to explicitly ack</span>
    <span class="comment">// them</span>
    <span class="keyword">return</span> msg.ack();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To configure the Kafka mapping we need a <code>microprofile-config.properties</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>kafka.bootstrap.servers=kafka:9092

mp.messaging.outgoing.to-kafka.connector=smallrye-kafka
mp.messaging.outgoing.to-kafka.topic=some-topic
mp.messaging.outgoing.to-kafka.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer
mp.messaging.outgoing.to-kafka.key.serializer=org.apache.kafka.common.serialization.StringSerializer

mp.messaging.incoming.from-kafka.connector=smallrye-kafka
mp.messaging.incoming.from-kafka.topic=some-topic
mp.messaging.incoming.from-kafka.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer
mp.messaging.incoming.from-kafka.key.deserializer=org.apache.kafka.common.serialization.StringDeserializer</code></pre>
</div>
</div>
<div class="paragraph">
<p>This configuration looks a lot like the previous configuration that we saw, but note that we need to specify the <code>key.serializer</code> for the outgoing channel, and the <code>key.deserializer</code> for the incoming channel. As before, they are implementations of <code>org.apache.kafka.common.serialization.Serializer</code> and <code>org.apache.kafka.common.serialization.Deserializer</code> respectively. Kafka provides implementations for basic types, and you may write your own and include them in the deployment.</p>
</div>
</div>
<div class="sect6">
<h7 id="a-note-on-org-apache-kafka-classes"><a class="anchor" href="#a-note-on-org-apache-kafka-classes"></a><a class="link" href="#a-note-on-org-apache-kafka-classes">A note on <code>org.apache.kafka</code> classes</a></h7>
<div class="paragraph">
<p>While we do expose the Kafka Clients jar in our BOMs, its usage is limited to</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Classes/interfaces exposed via the Kafka User API, e.g.:</p>
<div class="ulist">
<ul>
<li>
<p><code>org.apache.kafka.common.header.Header</code> and <code>org.apache.kafka.common.header.Headers</code> and implementations of those that are considered public API as per the Apache Kafka documentation.</p>
</li>
<li>
<p><code>org.apache.kafka.clients.consumer.ConsumerRecord</code></p>
</li>
<li>
<p><code>org.apache.kafka.common.record.TimestampType</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>Classes/interfaces needed for serialization and deserialization:</p>
<div class="ulist">
<ul>
<li>
<p><code>org.apache.kafka.common.serialization.Deserializer</code></p>
</li>
<li>
<p><code>org.apache.kafka.common.serialization.Serializer</code></p>
</li>
<li>
<p>Implementatations of <code>org.apache.kafka.common.serialization.Deserializer</code> and <code>org.apache.kafka.common.serialization.Serializer</code> in the <code>org.apache.kafka.common.serialization</code> package</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="component-reference-9"><a class="anchor" href="#component-reference-9"></a><a class="link" href="#component-reference-9">7.22.4. Component Reference</a></h4>
<div class="paragraph">
<p>The MicroProfile Reactive Messaging implementation is provided by the SmallRye Reactive Messaging project.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/eclipse/microprofile-reactive-messaging">MicroProfile Reactive Messaging</a></p>
</li>
<li>
<p><a href="https://github.com/smallrye/smallrye-reactive-messaging">SmallRye Reactive Messaging</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Web_services"><a class="anchor" href="#Web_services"></a><a class="link" href="#Web_services">7.23. Web services configuration</a></h3>
<div class="paragraph">
<p>JBossWS components are provided to the application server through the
webservices subsystem. JBossWS components handle the processing of WS
endpoints. The subsystem supports the configuration of published
endpoint addresses, and endpoint handler chains. A default webservice
subsystem is provided in the server&#8217;s domain and standalone
configuration files.</p>
</div>
<div class="sect3">
<h4 id="structure-of-the-webservices-subsystem"><a class="anchor" href="#structure-of-the-webservices-subsystem"></a><a class="link" href="#structure-of-the-webservices-subsystem">7.23.1. Structure of the webservices subsystem</a></h4>
<div class="sect4">
<h5 id="published-endpoint-address"><a class="anchor" href="#published-endpoint-address"></a><a class="link" href="#published-endpoint-address">Published endpoint address</a></h5>
<div class="paragraph">
<p>JBossWS supports the rewriting of the <code>&lt;soap:address&gt;</code> element of
endpoints published in WSDL contracts. This feature is useful for
controlling the server address that is advertised to clients for each
endpoint.</p>
</div>
<div class="paragraph">
<p>The following elements are available and can be modified (all are
optional):</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">modify-wsdl-address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This boolean enables and disables the
address rewrite functionality.When modify-wsdl-address is set to true
and the content of &lt;soap:address&gt; is a valid URL, JBossWS will rewrite
the URL using the values of wsdl-host and wsdl-port or
wsdl-secure-port.When modify-wsdl-address is set to false and the
content of &lt;soap:address&gt; is a valid URL, JBossWS will not rewrite the
URL. The &lt;soap:address&gt; URL will be used.When the content of
&lt;soap:address&gt; is not a valid URL, JBossWS will rewrite it no matter
what the setting of modify-wsdl-address.If modify-wsdl-address is set to
true and wsdl-host is not defined or explicitly set to
'jbossws.undefined.host' the content of &lt;soap:address&gt; URL is use.
JBossWS uses the requester&#8217;s host when rewriting the &lt;soap:address&gt;When
modify-wsdl-address is not defined JBossWS uses a default value of true.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">wsdl-host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The hostname / IP address to be used for rewriting
&lt;soap:address&gt;.If wsdl-host is set to jbossws.undefined.host, JBossWS
uses the requester&#8217;s host when rewriting the &lt;soap:address&gt;When
wsdl-host is not defined JBossWS uses a default value of
'jbossws.undefined.host'.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">wsdl-port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property to explicitly define the HTTP port
that will be used for rewriting the SOAP address.Otherwise the HTTP port
will be identified by querying the list of installed HTTP connectors.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">wsdl-secure-port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set this property to explicitly define the HTTPS
port that will be used for rewriting the SOAP address.Otherwise the
HTTPS port will be identified by querying the list of installed HTTPS
connectors.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">wsdl-uri-scheme</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This property explicitly sets the URI scheme
to use for rewriting &lt;soap:address&gt; . Valid values are http and https.
This configuration overrides scheme computed by processing the endpoint
(even if a transport guaranteeis specified). The provided values for
wsdl-port and wsdl-secure-port (or their default values) are used
depending on specified scheme.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">wsdl-path-rewrite-rule</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This string defines a SED substitution
command (e.g., 's/regexp/replacement/g') that JBossWS executes against
the path component of each &lt;soap:address&gt; URL published from the
server.When wsdl-path-rewrite-rule is not defined, JBossWS retains the
original path component of each &lt;soap:address&gt; URL.When
'modify-wsdl-address' is set to "false" this element is ignored.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="predefined-endpoint-configurations"><a class="anchor" href="#predefined-endpoint-configurations"></a><a class="link" href="#predefined-endpoint-configurations">Predefined endpoint configurations</a></h5>
<div class="paragraph">
<p>JBossWS enables extra setup configuration data to be predefined and
associated with an endpoint implementation. Predefined endpoint
configurations can be used for Jakarta XML Web Services client and Jakarta XML Web Services endpoint setup.
Endpoint configurations can include Jakarta XML Web Services handlers and key/value
properties declarations. This feature provides a convenient way to add
handlers to WS endpoints and to set key/value properties that control
JBossWS and Apache CXF internals (
<a href="https://docs.jboss.org/author/display/JBWS/Apache+CXF+integration#ApacheCXFintegration-Deploymentdescriptorproperties">see
Apache CXF configuration</a>).</p>
</div>
<div class="paragraph">
<p>The webservices subsystem provides
<a href="http://www.jboss.org/schema/jbossas/jboss-as-webservices_1_2.xsd">schema</a>
to support the definition of named sets of endpoint configuration data.
Annotation, <em>org.jboss.ws.api.annotation.EndpointConfig</em> is provided to
map the named configuration to the endpoint implementation.</p>
</div>
<div class="paragraph">
<p>There is no limit to the number of endpoint configurations that can be
defined within the webservices subsystem. Each endpoint configuration
must have a name that is unique within the webservices subsystem.
Endpoint configurations defined in the webservices subsystem are
available for reference by name through the annotation to any endpoint
in a deployed application.</p>
</div>
<div class="paragraph">
<p>WildFly ships with two predefined endpoint configurations.
Standard-Endpoint-Config is the default configuration.
Recording-Endpoint-Config is an example of custom endpoint configuration
and includes a recording handler.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;endpoint&quot; =&gt; {},
        &quot;modify-wsdl-address&quot; =&gt; true,
        &quot;wsdl-host&quot; =&gt; expression &quot;${jboss.bind.address:127.0.0.1}&quot;,
        &quot;endpoint-config&quot; =&gt; {
            &quot;Standard-Endpoint-Config&quot; =&gt; undefined,
            &quot;Recording-Endpoint-Config&quot; =&gt; undefined
        }
    }
}</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The <code>Standard-Endpoint-Config</code> is a special endpoint configuration. It
is used for any endpoint that does not have an explicitly assigned
endpoint configuration.
</td>
</tr>
</table>
</div>
<div class="sect5">
<h6 id="endpoint-configs"><a class="anchor" href="#endpoint-configs"></a><a class="link" href="#endpoint-configs">Endpoint configs</a></h6>
<div class="paragraph">
<p>Endpoint configs are defined using <code>the endpoint-config</code> element. Each
endpoint configuration may include properties and handlers set to the
endpoints associated to the configuration.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;post-handler-chain&quot; =&gt; undefined,
        &quot;property&quot; =&gt; undefined,
        &quot;pre-handler-chain&quot; =&gt; {&quot;recording-handlers&quot; =&gt; undefined}
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A new endpoint configuration can be added as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config:add
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-restart&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;restart-required&quot;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="handler-chains"><a class="anchor" href="#handler-chains"></a><a class="link" href="#handler-chains">Handler chains</a></h6>
<div class="paragraph">
<p>Each endpoint configuration may be associated with zero or more PRE and
POST handler chains. Each handler chain may include JAXWS handlers. For
outbound messages the PRE handler chains are executed before any handler
that is attached to the endpoint using the standard means, such as with
annotation @HandlerChain, and POST handler chains are executed after
those objects have executed. For inbound messages the POST handler
chains are executed before any handler that is attached to the endpoint
using the standard means and the PRE handler chains are executed after
those objects have executed.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>* Server inbound messages
Client --&gt; ... --&gt; POST HANDLER --&gt; ENDPOINT HANDLERS --&gt; PRE HANDLERS --&gt; Endpoint

* Server outbound messages
Endpoint --&gt; PRE HANDLER --&gt; ENDPOINT HANDLERS --&gt; POST HANDLERS --&gt; ... --&gt; Client</pre>
</div>
</div>
<div class="paragraph">
<p>The protocol-binding attribute must be used to set the protocols for
which the chain will be triggered.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config/pre-handler-chain=recording-handlers:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;protocol-bindings&quot; =&gt; &quot;##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM&quot;,
        &quot;handler&quot; =&gt; {&quot;RecordingHandler&quot; =&gt; undefined}
    },
    &quot;response-headers&quot; =&gt; {&quot;process-state&quot; =&gt; &quot;restart-required&quot;}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A new handler chain can be added as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers:add(protocol-bindings=&quot;##SOAP11_HTTP&quot;)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-restart&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;restart-required&quot;
    }
}
[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;handler&quot; =&gt; undefined,
        &quot;protocol-bindings&quot; =&gt; &quot;##SOAP11_HTTP&quot;
    },
    &quot;response-headers&quot; =&gt; {&quot;process-state&quot; =&gt; &quot;restart-required&quot;}
}</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="jaxws-handlers"><a class="anchor" href="#jaxws-handlers"></a><a class="link" href="#jaxws-handlers">Handlers</a></h6>
<div class="paragraph">
<p>JAXWS handler can be added in handler chains:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=Recording-Endpoint-Config/pre-handler-chain=recording-handlers/handler=RecordingHandler:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;class&quot; =&gt; &quot;org.jboss.ws.common.invocation.RecordingServerHandler&quot;},
    &quot;response-headers&quot; =&gt; {&quot;process-state&quot; =&gt; &quot;restart-required&quot;}
}
[standalone@localhost:9999 /] /subsystem=webservices/endpoint-config=My-Endpoint-Config/post-handler-chain=my-handlers/handler=foo-handler:add(class=&quot;org.jboss.ws.common.invocation.RecordingServerHandler&quot;)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-restart&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;restart-required&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Endpoint-config handler classloading</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>class</code> attribute is used to provide the fully qualified class name
of the handler. At deploy time, an instance of the class is created for
each referencing deployment. For class creation to succeed, the
deployment classloader must to be able to load the handler class.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="runtime-information"><a class="anchor" href="#runtime-information"></a><a class="link" href="#runtime-information">7.23.2. Runtime information</a></h4>
<div class="paragraph">
<p>Each web service endpoint is exposed through the deployment that
provides the endpoint implementation. Each endpoint can be queried as a
deployment resource. For further information please consult the chapter
"Application Deployment". Each web service endpoint specifies a web
context and a WSDL Url:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /deployment=&quot;*&quot;/subsystem=webservices/endpoint=&quot;*&quot;:read-resource
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [{
       &quot;address&quot; =&gt; [
           (&quot;deployment&quot; =&gt; &quot;jaxws-samples-handlerchain.war&quot;),
           (&quot;subsystem&quot; =&gt; &quot;webservices&quot;),
           (&quot;endpoint&quot; =&gt; &quot;jaxws-samples-handlerchain:TestService&quot;)
       ],
       &quot;outcome&quot; =&gt; &quot;success&quot;,
       &quot;result&quot; =&gt; {
           &quot;class&quot; =&gt; &quot;org.jboss.test.ws.jaxws.samples.handlerchain.EndpointImpl&quot;,
           &quot;context&quot; =&gt; &quot;jaxws-samples-handlerchain&quot;,
           &quot;name&quot; =&gt; &quot;TestService&quot;,
           &quot;type&quot; =&gt; &quot;JAXWS_JSE&quot;,
           &quot;wsdl-url&quot; =&gt; &quot;http://localhost:8080/jaxws-samples-handlerchain?wsdl&quot;
       }
   }]
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="ws-component-reference"><a class="anchor" href="#ws-component-reference"></a><a class="link" href="#ws-component-reference">7.23.3. Component Reference</a></h4>
<div class="paragraph">
<p>The web service subsystem is provided by the JBossWS project. For a
detailed description of the available configuration properties, please
consult the project documentation.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="ulist">
<ul>
<li>
<p>JBossWS homepage: <a href="http://www.jboss.org/jbossws" class="bare">http://www.jboss.org/jbossws</a></p>
</li>
<li>
<p>Project Documentation: <a href="https://docs.jboss.org/author/display/JBWS" class="bare">https://docs.jboss.org/author/display/JBWS</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Resource_adapters"><a class="anchor" href="#Resource_adapters"></a><a class="link" href="#Resource_adapters">7.24. Resource adapters</a></h3>
<div class="paragraph">
<p>Resource adapters are configured through the <em>resource-adapters</em>
subsystem. Declaring a new resource adapter consists of two separate
steps: You would need to deploy the .rar archive and define a resource
adapter entry in the subsystem.</p>
</div>
<div class="sect3">
<h4 id="resource-adapter-definitions"><a class="anchor" href="#resource-adapter-definitions"></a><a class="link" href="#resource-adapter-definitions">7.24.1. Resource Adapter Definitions</a></h4>
<div class="paragraph">
<p>The resource adapter itself is defined within the subsystem
<em>resource-adapters</em>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:resource-adapters:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;resource-adapters&gt;</span>
       <span class="tag">&lt;resource-adapter&gt;</span>
          <span class="tag">&lt;archive&gt;</span>eis.rar<span class="tag">&lt;/archive&gt;</span>
          <span class="comment">&lt;!-- Resource adapter level config-property --&gt;</span>
          <span class="tag">&lt;config-property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Server</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>localhost<span class="tag">&lt;/config-property&gt;</span>
          <span class="tag">&lt;config-property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Port</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>19000<span class="tag">&lt;/config-property&gt;</span>
          <span class="tag">&lt;transaction-support&gt;</span>XATransaction<span class="tag">&lt;/transaction-support&gt;</span>
          <span class="tag">&lt;connection-definitions&gt;</span>
             <span class="tag">&lt;connection-definition</span> <span class="attribute-name">class-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.acme.eis.ra.EISManagedConnectionFactory</span><span class="delimiter">&quot;</span></span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:/eis/AcmeConnectionFactory</span><span class="delimiter">&quot;</span></span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="attribute-name">pool-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">AcmeConnectionFactory</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="comment">&lt;!-- Managed connection factory level config-property --&gt;</span>
                <span class="tag">&lt;config-property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Name</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>Acme Inc<span class="tag">&lt;/config-property&gt;</span>
                <span class="tag">&lt;pool&gt;</span>
                   <span class="tag">&lt;min-pool-size&gt;</span>10<span class="tag">&lt;/min-pool-size&gt;</span>
                   <span class="tag">&lt;max-pool-size&gt;</span>100<span class="tag">&lt;/max-pool-size&gt;</span>
                <span class="tag">&lt;/pool&gt;</span>
                <span class="tag">&lt;security&gt;</span>
                   <span class="tag">&lt;application</span><span class="tag">/&gt;</span>
                <span class="tag">&lt;/security&gt;</span>
             <span class="tag">&lt;/connection-definition&gt;</span>
         <span class="tag">&lt;/connection-definitions&gt;</span>
         <span class="tag">&lt;admin-objects&gt;</span>
             <span class="tag">&lt;admin-object</span> <span class="attribute-name">class-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">com.acme.eis.ra.EISAdminObjectImpl</span><span class="delimiter">&quot;</span></span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="attribute-name">jndi-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">java:/eis/AcmeAdminObject</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;config-property</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Threshold</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>10<span class="tag">&lt;/config-property&gt;</span>
             <span class="tag">&lt;/admin-object&gt;</span>
         <span class="tag">&lt;/admin-objects&gt;</span>
       <span class="tag">&lt;/resource-adapter&gt;</span>
    <span class="tag">&lt;/resource-adapters&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note, that only JNDI bindings under java:/ or java:jboss/ are supported.</p>
</div>
<div class="paragraph">
<p><sub>(See</sub> <code>standalone/configuration/standalone.xml</code> <sub>)</sub></p>
</div>
</div>
<div class="sect3">
<h4 id="automatic-activation-of-resource-adapter-archives"><a class="anchor" href="#automatic-activation-of-resource-adapter-archives"></a><a class="link" href="#automatic-activation-of-resource-adapter-archives">7.24.2. Automatic activation of resource adapter archives</a></h4>
<div class="paragraph">
<p>A resource adapter archive can be automatically activated with a
configuration by including an META-INF/ironjacamar.xml in the archive.</p>
</div>
<div class="paragraph">
<p>The schema can be found at
<a href="http://docs.jboss.org/ironjacamar/schema/ironjacamar_1_0.xsd" class="bare">http://docs.jboss.org/ironjacamar/schema/ironjacamar_1_0.xsd</a></p>
</div>
</div>
<div class="sect3">
<h4 id="ra-component-reference"><a class="anchor" href="#ra-component-reference"></a><a class="link" href="#ra-component-reference">7.24.3. Component Reference</a></h4>
<div class="paragraph">
<p>The resource adapter subsystem is provided by the
<a href="http://www.jboss.org/ironjacamar">IronJacamar</a> project. For a detailed
description of the available configuration properties, please consult
the project documentation.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>IronJacamar homepage: <a href="http://www.jboss.org/ironjacamar" class="bare">http://www.jboss.org/ironjacamar</a></p>
</li>
<li>
<p>Project Documentation: <a href="http://www.jboss.org/ironjacamar/docs" class="bare">http://www.jboss.org/ironjacamar/docs</a></p>
</li>
<li>
<p>Schema description:
<a href="http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.html#deployingra_descriptor" class="bare">http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.html#deployingra_descriptor</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Jakarta_Batch"><a class="anchor" href="#Jakarta_Batch"></a><a class="link" href="#Jakarta_Batch">7.25. Jakarta Batch Subsystem Configuration</a></h3>
<div class="quoteblock abstract">
<blockquote>
The batch subsystem is used to configure an environment for running
batch applications. <a href="http://wildfly.org">WildFly</a> uses
<a href="https://github.com/jberet/jsr352">JBeret</a> for it&#8217;s batch implementation.
Specific information about JBeret can be found in the
<a href="http://jberet.gitbooks.io/jberet-user-guide/content/">user guide</a>. The
resource path, in <a href="#CLI_Recipes">CLI notation</a>, for the subsystem
is <code>subsystem=batch-jberet</code>.
</blockquote>
</div>
<div class="sect3">
<h4 id="default-subsystem-configuration"><a class="anchor" href="#default-subsystem-configuration"></a><a class="link" href="#default-subsystem-configuration">7.25.1. Default Subsystem Configuration</a></h4>
<div class="paragraph">
<p>For up to date information about subsystem configuration options see the
<a href="wildscribe" target="_blank" rel="noopener">WildFly model reference</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="security"><a class="anchor" href="#security"></a><a class="link" href="#security">7.25.2. Security</a></h4>
<div class="paragraph">
<p>A new <code>security-domain</code> attribute was added to the <code>batch-jberet</code>
subsystem to allow batch jobs to be executed under that security domain.
Jobs that are stopped as part of a <code>suspend</code> operation will be restarted
on execution of a <code>resume</code> with the original user that started job.</p>
</div>
<div class="paragraph">
<p>There was a
<code>org.wildfly.extension.batch.jberet.deployment.BatchPermission</code> added to
allow a security restraint to various batch functions. The following
functions can be controlled with this permission.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>start</p>
</li>
<li>
<p>stop</p>
</li>
<li>
<p>restart</p>
</li>
<li>
<p>abandon</p>
</li>
<li>
<p>read</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The read function allows users to use the getter methods from the
<code>jakarta.batch.operations.JobOperator</code> or read the <code>batch-jberet</code>
deployment resource, for example
<code>/deployment=my.war/subsystem=batch-jberet:read-resource</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="job-repository"><a class="anchor" href="#job-repository"></a><a class="link" href="#job-repository">7.25.3. Job Repository</a></h4>
<div class="paragraph">
<p>The batch subsystem supports 2 types of job repository:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>in-memory job repository: all job execution data are kept in the memory
of WildFly instance. When the server shuts down, all job execution data
are lost. In a clustered environment, each WildFly server instance has its
own in-memory job repository, and it is not possible to share job execution
data between WildFly instances. This is the default job repository in
batch subsystem.</p>
</li>
<li>
<p>jdbc job repository: all job execution data are saved in a relational
database accessed via jdbc. In a clustered environment, a jdbc job repository
can be used to share job execution data between WildFly instances.
For example, one may start a job execution in one instance, stop and restart
it from a different WildFly instance.</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="handling-large-job-repositories"><a class="anchor" href="#handling-large-job-repositories"></a><a class="link" href="#handling-large-job-repositories">Handling Large Job Repositories</a></h5>
<div class="paragraph">
<p>In some cases, when a job repository accumulates a large number of job
execution records (say hundreds of thousands), application deployment times may
be negatively impacted. This is relevant mainly to persistent job repository
implementations, like the jdbc job repository.</p>
</div>
<div class="paragraph">
<p>In order to avoid accumulating too high a number of job execution records, the
application can delete old executions via
<code>JobOperator.abandon(long executionId)</code>, or other means like pruning the
database tables can be employed.</p>
</div>
<div class="paragraph">
<p>If it&#8217;s no possible to avoid storing large number of job execution records,
the job repositories can be configured to limit the number of job executions
that is returned by them by setting the <code>execution-records-limit</code> attribute.
If the attribute is set, Wildfly will only load specified maximum number of
job executions from the backing storage mechanism.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="deployment-descriptors"><a class="anchor" href="#deployment-descriptors"></a><a class="link" href="#deployment-descriptors">7.25.4. Deployment Descriptors</a></h4>
<div class="paragraph">
<p>There are no deployment descriptors for configuring a batch environment
defined by the <a href="https://www.jcp.org/en/jsr/detail?id=352">JSR-352
specification</a>. In <a href="http://wildfly.org">WildFly</a> you can use a
<code>jboss-all.xml</code> deployment descriptor to define aspects of the batch
environment for your deployment.</p>
</div>
<div class="paragraph">
<p>In the <code>jboss-all.xml</code> deployment descriptor you can define a named job
repository, a new job repository and/or a named thread pool. A named job
repository and named thread pool are resources defined on the batch
subsystem. Only a named thread pool is allowed to be defined in the
deployment descriptor.</p>
</div>
<div class="listingblock">
<div class="title">Example Named Job Repository and Thread Pool</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;jboss</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;batch</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:batch-jberet:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
      <span class="tag">&lt;job-repository&gt;</span>
        <span class="tag">&lt;named</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">batch-ds</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
      <span class="tag">&lt;/job-repository&gt;</span>
      <span class="tag">&lt;thread-pool</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">deployment-thread-pool</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/batch&gt;</span>
<span class="tag">&lt;/jboss&gt;</span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Example new Job Repository</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;jboss</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;batch</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:batch-jberet:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;job-repository&gt;</span>
            <span class="tag">&lt;jdbc</span> <span class="attribute-name">data-source</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">batch-ds</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/job-repository&gt;</span>
    <span class="tag">&lt;/batch&gt;</span>
<span class="tag">&lt;/jboss&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="deployment-resources"><a class="anchor" href="#deployment-resources"></a><a class="link" href="#deployment-resources">7.25.5. Deployment Resources</a></h4>
<div class="paragraph">
<p>Some subsystems in <a href="http://wildfly.org">WildFly</a> register runtime
resources for deployments. The batch subsystem registers jobs and
executions. The jobs are registered using the job name, this is <em>not</em>
the job XML name. Executions are registered using the execution id.</p>
</div>
<div class="listingblock">
<div class="title">Batch application in a standalone server</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-jdbc-chunk.war/subsystem=batch-jberet:read-resource(recursive=true,include-runtime=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;job&quot; =&gt; {
        &quot;reader-3&quot; =&gt; {
            &quot;instance-count&quot; =&gt; 1,
            &quot;running-executions&quot; =&gt; 0,
            &quot;execution&quot; =&gt; {&quot;1&quot; =&gt; {
                &quot;batch-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;create-time&quot; =&gt; &quot;2015-08-07T15:37:06.416-0700&quot;,
                &quot;end-time&quot; =&gt; &quot;2015-08-07T15:37:06.519-0700&quot;,
                &quot;exit-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;instance-id&quot; =&gt; 1L,
                &quot;last-updated-time&quot; =&gt; &quot;2015-08-07T15:37:06.519-0700&quot;,
                &quot;start-time&quot; =&gt; &quot;2015-08-07T15:37:06.425-0700&quot;
            }}
        },
        &quot;reader-5&quot; =&gt; {
            &quot;instance-count&quot; =&gt; 0,
            &quot;running-executions&quot; =&gt; 0,
            &quot;execution&quot; =&gt; undefined
        }
    }}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The batch subsystem resource on a deployment also has 3 operations to
interact with batch jobs on the selected deployment. There is a
<code>start-job</code>, <code>stop-job</code> and <code>restart-job</code> operation. The <code>execution</code>
resource also has a <code>stop-job</code> and <code>restart-job</code> operation.</p>
</div>
<div class="listingblock">
<div class="title">Example start-job</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:start-job(job-xml-name=simple, properties={writer.sleep=5000})
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; 1L
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Example stop-job</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:stop-job(execution-id=2)</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Example restart-job</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:restart-job(execution-id=2)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; 3L
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Result of resource after the 3 executions</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:read-resource(recursive=true, include-runtime=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;job&quot; =&gt; {&quot;chunkPartition&quot; =&gt; {
        &quot;instance-count&quot; =&gt; 2,
        &quot;running-executions&quot; =&gt; 0,
        &quot;execution&quot; =&gt; {
            &quot;1&quot; =&gt; {
                &quot;batch-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;create-time&quot; =&gt; &quot;2015-08-07T15:41:55.504-0700&quot;,
                &quot;end-time&quot; =&gt; &quot;2015-08-07T15:42:15.513-0700&quot;,
                &quot;exit-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;instance-id&quot; =&gt; 1L,
                &quot;last-updated-time&quot; =&gt; &quot;2015-08-07T15:42:15.513-0700&quot;,
                &quot;start-time&quot; =&gt; &quot;2015-08-07T15:41:55.504-0700&quot;
            },
            &quot;2&quot; =&gt; {
                &quot;batch-status&quot; =&gt; &quot;STOPPED&quot;,
                &quot;create-time&quot; =&gt; &quot;2015-08-07T15:44:39.879-0700&quot;,
                &quot;end-time&quot; =&gt; &quot;2015-08-07T15:44:54.882-0700&quot;,
                &quot;exit-status&quot; =&gt; &quot;STOPPED&quot;,
                &quot;instance-id&quot; =&gt; 2L,
                &quot;last-updated-time&quot; =&gt; &quot;2015-08-07T15:44:54.882-0700&quot;,
                &quot;start-time&quot; =&gt; &quot;2015-08-07T15:44:39.879-0700&quot;
            },
            &quot;3&quot; =&gt; {
                &quot;batch-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;create-time&quot; =&gt; &quot;2015-08-07T15:45:48.162-0700&quot;,
                &quot;end-time&quot; =&gt; &quot;2015-08-07T15:45:53.165-0700&quot;,
                &quot;exit-status&quot; =&gt; &quot;COMPLETED&quot;,
                &quot;instance-id&quot; =&gt; 2L,
                &quot;last-updated-time&quot; =&gt; &quot;2015-08-07T15:45:53.165-0700&quot;,
                &quot;start-time&quot; =&gt; &quot;2015-08-07T15:45:48.163-0700&quot;
            }
        }
    }}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Pro Tip</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You can filter jobs by an attribute on the execution resource with the
<code>query</code> operation.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">View all stopped jobs</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/deployment=batch-chunk.war/subsystem=batch-jberet/job=*/execution=*:query(where=[&quot;batch-status&quot;, &quot;STOPPED&quot;])</code></pre>
</div>
</div>
<div class="paragraph">
<p>As with all operations you can see details about the operation using the
<code>:read-operation-description</code> operation.</p>
</div>
<div class="paragraph">
<p>Tab completion</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Don&#8217;t forget that CLI has tab completion which will complete operations
and attributes (arguments) on operations.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">Example start-job operation description</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:read-operation-description(name=start-job)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;operation-name&quot; =&gt; &quot;start-job&quot;,
        &quot;description&quot; =&gt; &quot;Starts a batch job.&quot;,
        &quot;request-properties&quot; =&gt; {
            &quot;job-xml-name&quot; =&gt; {
                &quot;type&quot; =&gt; STRING,
                &quot;description&quot; =&gt; &quot;The name of the job XML file to use when starting the job.&quot;,
                &quot;expressions-allowed&quot; =&gt; false,
                &quot;required&quot; =&gt; true,
                &quot;nillable&quot; =&gt; false,
                &quot;min-length&quot; =&gt; 1L,
                &quot;max-length&quot; =&gt; 2147483647L
            },
            &quot;properties&quot; =&gt; {
                &quot;type&quot; =&gt; OBJECT,
                &quot;description&quot; =&gt; &quot;Optional properties to use when starting the batch job.&quot;,
                &quot;expressions-allowed&quot; =&gt; false,
                &quot;required&quot; =&gt; false,
                &quot;nillable&quot; =&gt; true,
                &quot;value-type&quot; =&gt; STRING
            }
        },
        &quot;reply-properties&quot; =&gt; {&quot;type&quot; =&gt; LONG},
        &quot;read-only&quot; =&gt; false,
        &quot;runtime-only&quot; =&gt; true
    }
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Jakarta_Server_Faces"><a class="anchor" href="#Jakarta_Server_Faces"></a><a class="link" href="#Jakarta_Server_Faces">7.26. Jakarta Server Faces Configuration</a></h3>
<div class="quoteblock abstract">
<blockquote>
Jakarta Server Faces configuration is handled by the Jakarta Server Faces subsystem. The Jakarta Server Faces subsystem
allows multiple Jakarta Server Faces implementations to be installed on the same WildFly
server. In particular, any version of Mojarra or MyFaces that implements
spec level 2.1 or higher can be installed. For each Jakarta Server Faces implementation,
a new slot needs to be created under <code>com.sun.jsf-impl</code>,
<code>jakarta.faces.api</code>, and <code>org.jboss.as.jsf-injection</code>. When the Jakarta Server Faces
subsystem starts up, it scans the module path to find all of the Jakarta Server Faces
implementations that have been installed. The default Jakarta Server Faces implementation
that WildFly should use is defined by the <code>default-jsf-impl-slot</code>
attribute.
</blockquote>
</div>
<div class="sect3">
<h4 id="installing-a-new-jsf-implementation-manually"><a class="anchor" href="#installing-a-new-jsf-implementation-manually"></a><a class="link" href="#installing-a-new-jsf-implementation-manually">7.26.1. Installing a new Jakarta Server Faces implementation manually</a></h4>
<div class="paragraph">
<p>A new Jakarta Server Faces implementation can be manually installed as follows:</p>
</div>
<div class="sect4">
<h5 id="add-a-module-slot-for-the-new-jsf-implementation-jar"><a class="anchor" href="#add-a-module-slot-for-the-new-jsf-implementation-jar"></a><a class="link" href="#add-a-module-slot-for-the-new-jsf-implementation-jar">Add a module slot for the new Jakarta Server Faces implementation JAR</a></h5>
<div class="ulist">
<ul>
<li>
<p>Create the following directory structure under the
WILDFLY_HOME/modules directory:<br>
WILDFLY_HOME/modules/com/sun/jsf-impl/&lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;<br>
<br>
For example, for Mojarra 2.2.11, the above path would resolve to:<br>
WILDFLY_HOME/modules/com/sun/jsf-impl/mojarra-2.2.11</p>
</li>
<li>
<p>Place the Jakarta Server Faces implementation JAR in the &lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;
subdirectory. In the same subdirectory, add a <code>module.xml</code> file similar
to the
<a href="https://github.com/wildfly/wildfly/blob/main/jsf/multi-jsf-installer/src/main/resources/mojarra-impl-module.xml">Mojarra</a>
or
<a href="https://github.com/wildfly/wildfly/blob/main/jsf/multi-jsf-installer/src/main/resources/myfaces-impl-module.xml">MyFaces</a>
template examples. Change the <code>resource-root-path</code> to the name of your
Jakarta Server Faces implementation JAR and fill in appropriate values for $\{
<code>jsf-impl-name</code>} and $\{ <code>jsf-version</code>}.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="add-a-module-slot-for-the-new-jsf-api-jar"><a class="anchor" href="#add-a-module-slot-for-the-new-jsf-api-jar"></a><a class="link" href="#add-a-module-slot-for-the-new-jsf-api-jar">Add a module slot for the new Jakarta Server Faces API JAR</a></h5>
<div class="ulist">
<ul>
<li>
<p>Create the following directory structure under the
WILDFLY_HOME/modules directory:<br>
WILDFLY_HOME/modules/jakarta/faces/api/&lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;</p>
</li>
<li>
<p>Place the JSF API JAR in the &lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;
subdirectory. In the same subdirectory, add a <code>module.xml</code> file similar
to the
<a href="https://github.com/wildfly/wildfly/blob/main/jsf/multi-jsf-installer/src/main/resources/mojarra-api-module.xml">Mojarra</a>
or
<a href="https://github.com/wildfly/wildfly/blob/main/jsf/multi-jsf-installer/src/main/resources/myfaces-api-module.xml">MyFaces</a>
template examples. Change the <code>resource-root-path</code> to the name of your
Jakarta Server Faces API JAR and fill in appropriate values for $\{ <code>jsf-impl-name</code>} and
$\{ <code>jsf-version</code>}.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="add-a-module-slot-for-the-jsf-injection-jar"><a class="anchor" href="#add-a-module-slot-for-the-jsf-injection-jar"></a><a class="link" href="#add-a-module-slot-for-the-jsf-injection-jar">Add a module slot for the Jakarta Server Faces injection JAR</a></h5>
<div class="ulist">
<ul>
<li>
<p>Create the following directory structure under the
WILDFLY_HOME/modules directory:<br>
WILDFLY_HOME/modules/org/jboss/as/jsf-injection/&lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;</p>
</li>
<li>
<p>Copy the wildfly-jsf-injection JAR and the weld-core-jsf JAR from
WILDFLY_HOME/modules/system/layers/base/org/jboss/as/jsf-injection/main
to the &lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt; subdirectory.</p>
</li>
<li>
<p>In the &lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt; subdirectory, add a <code>module.xml</code>
file similar to the
<a href="https://gist.github.com/fjuma/30160f0e95ade328253118c706339604">Mojarra</a>
or
<a href="https://gist.github.com/fjuma/f73b05c3864255e7b10b49f989f0b75e">MyFaces</a>
template examples and fill in appropriate values for $\{
<code>jsf-impl-name</code>}, $\{ <code>jsf-version</code>}, $\{ <code>version.jboss.as</code>}, and $\{
<code>version.weld.core</code>}. (These last two placeholders depend on the
versions of the wildfly-jsf-injection and weld-core-jsf JARs that were
copied over in the previous step.)</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="for-myfaces-only---add-a-module-for-the-commons-digester-jar"><a class="anchor" href="#for-myfaces-only---add-a-module-for-the-commons-digester-jar"></a><a class="link" href="#for-myfaces-only---add-a-module-for-the-commons-digester-jar">For MyFaces only - add a module for the commons-digester JAR</a></h5>
<div class="ulist">
<ul>
<li>
<p>Create the following directory structure under the
WILDFLY_HOME/modules directory:<br>
WILDFLY_HOME/modules/org/apache/commons/digester/main</p>
</li>
<li>
<p>Place the
<a href="http://search.maven.org/remotecontent?filepath=commons-digester/commons-digester/1.8/commons-digester-1.8.jar">commons-digester</a>
JAR in WILDFLY_HOME/modules/org/apache/commons/digester/main. In the
<code>main</code> subdirectory, add a <code>module.xml</code> file similar to this
<a href="https://github.com/wildfly/wildfly/blob/main/jsf/multi-jsf-installer/src/main/resources/myfaces-digester-module.xml">template</a>.
Fill in the appropriate value for $\{ <code>version.commons-digester</code>}.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="start-the-server"><a class="anchor" href="#start-the-server"></a><a class="link" href="#start-the-server">Start the server</a></h5>
<div class="paragraph">
<p>After starting the server, the following CLI command can be used to
verify that your new Jakarta Server Faces implementation has been installed successfully.
The new Jakarta Server Faces implementation should appear in the output of this command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=jsf:list-active-jsf-impls()</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="changing-the-default-jsf-implementation"><a class="anchor" href="#changing-the-default-jsf-implementation"></a><a class="link" href="#changing-the-default-jsf-implementation">7.26.2. Changing the default Jakarta Server Faces implementation</a></h4>
<div class="paragraph">
<p>The following CLI command can be used to make a newly installed Jakarta Server Faces
implementation the default Jakarta Server Faces implementation used by WildFly:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=jsf/:write-attribute(name=default-jsf-impl-slot,value=&lt;JSF_IMPL_NAME&gt;-&lt;JSF_VERSION&gt;)</code></pre>
</div>
</div>
<div class="paragraph">
<p>A server restart will be required for this change to take effect.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-a-jsf-app-to-use-a-non-default-jsf-implementation"><a class="anchor" href="#configuring-a-jsf-app-to-use-a-non-default-jsf-implementation"></a><a class="link" href="#configuring-a-jsf-app-to-use-a-non-default-jsf-implementation">7.26.3. Configuring a Jakarta Server Faces app to use a non-default Jakarta Server Faces implementation</a></h4>
<div class="paragraph">
<p>A Jakarta Server Faces app can be configured to use an installed Jakarta Server Faces implementation
that&#8217;s not the default implementation by adding a
<code>org.jboss.jbossfaces.JSF_CONFIG_NAME</code> context parameter to its
<code>web.xml</code> file. For example, to indicate that a Jakarta Server Faces app should use
MyFaces 2.2.12 (assuming MyFaces 2.2.12 has been installed on the
server), the following context parameter would need to be added:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;context-param&gt;</span>
  <span class="tag">&lt;param-name&gt;</span>org.jboss.jbossfaces.JSF_CONFIG_NAME<span class="tag">&lt;/param-name&gt;</span>
  <span class="tag">&lt;param-value&gt;</span>myfaces-2.2.12<span class="tag">&lt;/param-value&gt;</span>
<span class="tag">&lt;/context-param&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If a Jakarta Server Faces app does not specify this context parameter, the default Jakarta Server Faces
implementation will be used for that app.</p>
</div>
</div>
<div class="sect3">
<h4 id="disallowing-doctype-declarations"><a class="anchor" href="#disallowing-doctype-declarations"></a><a class="link" href="#disallowing-doctype-declarations">7.26.4. Disallowing DOCTYPE declarations</a></h4>
<div class="paragraph">
<p>The following CLI commands can be used to disallow DOCTYPE declarations
in Jakarta Server Faces deployments:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=jsf:write-attribute(name=disallow-doctype-decl, value=true)
reload</code></pre>
</div>
</div>
<div class="paragraph">
<p>This setting can be overridden for a particular Jakarta Server Faces deployment by
adding the <code>com.sun.faces.disallowDoctypeDecl</code> context parameter
to the deployment&#8217;s <code>web.xml</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;context-param&gt;</span>
  <span class="tag">&lt;param-name&gt;</span>com.sun.faces.disallowDoctypeDecl<span class="tag">&lt;/param-name&gt;</span>
  <span class="tag">&lt;param-value&gt;</span>false<span class="tag">&lt;/param-value&gt;</span>
<span class="tag">&lt;/context-param&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="JMX"><a class="anchor" href="#JMX"></a><a class="link" href="#JMX">7.27. JMX subsystem configuration</a></h3>
<div class="paragraph">
<p>The JMX subsystem registers a service with the Remoting endpoint so that
remote access to JMX can be obtained over the exposed Remoting
connector.</p>
</div>
<div class="paragraph">
<p>This is switched on by default in standalone mode and accessible over
port 9990 but in domain mode is switched off so needs to be enabled - in
domain mode the port will be the port of the Remoting connector for the
WildFly instance to be monitored.</p>
</div>
<div class="paragraph">
<p>To use the connector you can access it in the standard way using a
<code>service:jmx</code> URL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">import</span> <span class="include">javax.management.MBeanServerConnection</span>;
<span class="keyword">import</span> <span class="include">javax.management.remote.JMXConnector</span>;
<span class="keyword">import</span> <span class="include">javax.management.remote.JMXConnectorFactory</span>;
<span class="keyword">import</span> <span class="include">javax.management.remote.JMXServiceURL</span>;
<span class="error"> </span>
<span class="directive">public</span> <span class="type">class</span> <span class="class">JMXExample</span> {
<span class="error"> </span>
    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="comment">//Get a connection to the WildFly MBean server on localhost</span>
        <span class="predefined-type">String</span> host = <span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span>;
        <span class="type">int</span> port = <span class="integer">9990</span>;  <span class="comment">// management-web port</span>
        <span class="predefined-type">String</span> urlString =
            <span class="predefined-type">System</span>.getProperty(<span class="string"><span class="delimiter">&quot;</span><span class="content">jmx.service.url</span><span class="delimiter">&quot;</span></span>,<span class="string"><span class="delimiter">&quot;</span><span class="content">service:jmx:remote+http://</span><span class="delimiter">&quot;</span></span> + host + <span class="string"><span class="delimiter">&quot;</span><span class="content">:</span><span class="delimiter">&quot;</span></span> + port);
        <span class="predefined-type">JMXServiceURL</span> serviceURL = <span class="keyword">new</span> <span class="predefined-type">JMXServiceURL</span>(urlString);
        <span class="predefined-type">JMXConnector</span> jmxConnector = <span class="predefined-type">JMXConnectorFactory</span>.connect(serviceURL, <span class="predefined-constant">null</span>);
        <span class="predefined-type">MBeanServerConnection</span> connection = jmxConnector.getMBeanServerConnection();
<span class="error"> </span>
        <span class="comment">//Invoke on the WildFly MBean server</span>
        <span class="type">int</span> count = connection.getMBeanCount();
        <span class="predefined-type">System</span>.out.println(count);
       <span class="error"> </span>jmxConnector.close();
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You also need to set your classpath when running the above example. The
following script covers Linux. If your environment is much different,
paste your script when you have it working.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>!/bin/bash

# specify your WildFly folder +
export YOUR_JBOSS_HOME=~/WildFly

java -classpath $YOUR_JBOSS_HOME/bin/client/jboss-client.jar:./
JMXExample</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also connect using jconsole.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If using jconsole use the <code>jconsole.sh</code> and <code>jconsole.bat</code> scripts
included in the /bin directory of the WildFly distribution as these set
the classpath as required to connect over Remoting.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In addition to the standard JVM MBeans, the WildFly MBean server
contains the following MBeans:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">JMX ObjectName</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.msc:type=container,name=jboss-as</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Exposes management operations
on the JBoss Modular Service Container, which is the dependency
injection framework at the heart of WildFly. It is useful for debugging
dependency problems, for example if you are integrating your own
subsystems, as it exposes operations to dump all services and their
current states</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.naming:type=JNDIView</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Shows what is bound in JNDI</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.modules:type=ModuleLoader,name=*</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This collection of MBeans
exposes management operations on JBoss Modules classloading layer. It is
useful for debugging dependency problems arising from missing module
dependencies</p></td>
</tr>
</tbody>
</table>
<div class="sect3">
<h4 id="audit-logging"><a class="anchor" href="#audit-logging"></a><a class="link" href="#audit-logging">7.27.1. Audit logging</a></h4>
<div class="paragraph">
<p>Audit logging for the JMX MBean server managed by the JMX subsystem. The
resource is at <code>/subsystem=jmx/configuration=audit-log</code> and its
attributes are similar to the ones mentioned for
<code>/core-service=management/access=audit/logger=audit-log</code> in
<a href="#Audit_logging">Audit logging</a>.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enabled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true to enable logging of the JMX operations</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">log-boot</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true to log the JMX operations when booting the server, false
otherwise</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">log-read-only</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true all operations will be audit logged, if false
only operations that change the model will be logged</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Then which handlers are used to log the management operations are
configured as <code>handler=*</code> children of the logger. These handlers and
their formatters are defined in the global
<code>/core-service=management/access=audit</code> section mentioned in
<a href="#Audit_logging">Audit logging</a>.</p>
</div>
<div class="sect4">
<h5 id="json-formatter-jmx"><a class="anchor" href="#json-formatter-jmx"></a><a class="link" href="#json-formatter-jmx">JSON Formatter</a></h5>
<div class="paragraph">
<p>The same JSON Formatter is used as described in
<a href="#Audit_logging">Audit logging</a>. However the records for MBean
Server invocations have slightly different fields from those logged for
the core management layer.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>2013-08-29 18:26:29 - {
    &quot;type&quot; : &quot;jmx&quot;,
    &quot;r/o&quot; : false,
    &quot;booting&quot; : false,
    &quot;version&quot; : &quot;10.0.0.Final&quot;,
    &quot;user&quot; : &quot;$local&quot;,
    &quot;domainUUID&quot; : null,
    &quot;access&quot; : &quot;JMX&quot;,
    &quot;remote-address&quot; : &quot;127.0.0.1/127.0.0.1&quot;,
    &quot;method&quot; : &quot;invoke&quot;,
    &quot;sig&quot; : [
        &quot;javax.management.ObjectName&quot;,
        &quot;java.lang.String&quot;,
        &quot;[Ljava.lang.Object;&quot;,
        &quot;[Ljava.lang.String;&quot;
    ],
    &quot;params&quot; : [
        &quot;java.lang:type=Threading&quot;,
        &quot;getThreadInfo&quot;,
        &quot;[Ljava.lang.Object;@5e6c33c&quot;,
        &quot;[Ljava.lang.String;@4b681c69&quot;
    ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>It includes an optional timestamp and then the following information in
the json record</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This will have the value jmx meaning it comes from the jmx
subsystem</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">r/o</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if the operation has read only impact on the MBean(s)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">booting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if the operation was executed during the bootup process,
false if it was executed once the server is up and running</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">version</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The version number of the WildFly instance</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">user</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The username of the authenticated user.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">domainUUID</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This is not currently populated for JMX operations</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">access</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This can have one of the following values:*NATIVE - The
operation came in through the native management interface, for example
the CLI*HTTP - The operation came in through the domain HTTP interface,
for example the admin console*JMX - The operation came in through the
JMX subsystem. See JMX for how to configure audit logging for JMX.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">remote-address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The address of the client executing this operation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the called MBeanServer method</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">sig</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The signature of the called called MBeanServer method</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">params</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The actual parameters passed in to the MBeanServer method, a
simple Object.toString() is called on each parameter.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">error</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If calling the MBeanServer method resulted in an error, this
field will be populated with Throwable.getMessage()</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Deployment_Scanner"><a class="anchor" href="#Deployment_Scanner"></a><a class="link" href="#Deployment_Scanner">7.28. Deployment Scanner configuration</a></h3>
<div class="paragraph">
<p>The deployment scanner is only used in standalone mode. Its job is to
monitor a directory for new files and to deploy those files. It can be
found in <code>standalone.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:deployment-scanner:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;deployment-scanner</span> <span class="attribute-name">scan-interval</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">5000</span><span class="delimiter">&quot;</span></span>
      <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.base.dir</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">deployments</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>You can define more <code>deployment-scanner</code> entries to scan for deployments
from more locations. The configuration showed will scan the
<code>JBOSS_HOME/standalone/deployments</code> directory every five seconds. The
runtime model is shown below, and uses default values for attributes not
specified in the xml:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9999 /] /subsystem=deployment-scanner:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;scanner&quot; =&gt; {&quot;default&quot; =&gt; {
        &quot;auto-deploy-exploded&quot; =&gt; false,
        &quot;auto-deploy-zipped&quot; =&gt; true,
        &quot;deployment-timeout&quot; =&gt; 60L,
        &quot;name&quot; =&gt; &quot;default&quot;,
        &quot;path&quot; =&gt; &quot;deployments&quot;,
        &quot;relative-to&quot; =&gt; &quot;jboss.server.base.dir&quot;,
        &quot;scan-enabled&quot; =&gt; true,
        &quot;scan-interval&quot; =&gt; 5000
    }}}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The attributes are</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">STRING</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the scanner. default is used if not specified</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">STRING</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The actual filesystem path to be scanned. Treated as an
absolute path, unless the 'relative-to' attribute is specified, in which
case the value is treated as relative to that path.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">relative-to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">STRING</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Reference to a filesystem path defined in the
"paths" section of the server configuration, or one of the system
properties specified on startup. In the example above
jboss.server.base.dir resolves to JBOSS_HOME/standalone</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">scan-enabled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">BOOLEAN</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true scanning is enabled</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">scan-interval</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">INT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Periodic interval, in milliseconds, at which the
repository should be scanned for changes. A value of less than 1
indicates the repository should only be scanned at initial startup.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">auto-deploy-zipped</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">BOOLEAN</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls whether zipped deployment content
should be automatically deployed by the scanner without requiring the
user to add a .dodeploy marker file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">auto-deploy-exploded</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">BOOLEAN</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls whether exploded deployment
content should be automatically deployed by the scanner without
requiring the user to add a .dodeploy marker file. Setting this to
'true' is not recommended for anything but basic development scenarios,
as there is no way to ensure that deployment will not occur in the
middle of changes to the content.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">auto-deploy-xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">BOOLEAN</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Controls whether XML content should be
automatically deployed by the scanner without requiring a .dodeploy
marker file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">deployment-timeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LONG</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Timeout, in seconds, a deployment is allows
to execute before being canceled. The default is 60 seconds.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Deployment scanners can be added by modifying <code>standalone.xml</code> before
starting up the server or they can be added and removed at runtime using
the CLI</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=deployment-scanner/scanner=new:add(scan-interval=10000,relative-to=&quot;jboss.server.base.dir&quot;,path=&quot;other-deployments&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}
[standalone@localhost:9990 /] /subsystem=deployment-scanner/scanner=new:remove
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also change the attributes at runtime, so for example to turn
off scanning you can do</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /subsystem=deployment-scanner/scanner=default:write-attribute(name=&quot;scan-enabled&quot;,value=false)
{&quot;outcome&quot; =&gt; &quot;success&quot;}
[standalone@localhost:9990 /] /subsystem=deployment-scanner:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;scanner&quot; =&gt; {&quot;default&quot; =&gt; {
        &quot;auto-deploy-exploded&quot; =&gt; false,
        &quot;auto-deploy-zipped&quot; =&gt; true,
        &quot;deployment-timeout&quot; =&gt; 60L,
        &quot;name&quot; =&gt; &quot;default&quot;,
        &quot;path&quot; =&gt; &quot;deployments&quot;,
        &quot;relative-to&quot; =&gt; &quot;jboss.server.base.dir&quot;,
        &quot;scan-enabled&quot; =&gt; false,
        &quot;scan-interval&quot; =&gt; 5000
    }}}
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Core_Management"><a class="anchor" href="#Core_Management"></a><a class="link" href="#Core_Management">7.29. Core Management Subsystem Configuration</a></h3>
<div class="paragraph">
<p>The core management subsystem is composed services used to manage the
server or monitor its status.<br>
The core management subsystem configuration may be used to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>register a listener for a server lifecycle events.</p>
</li>
<li>
<p>list the last configuration changes on a server.</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="lifecycle-listener"><a class="anchor" href="#lifecycle-listener"></a><a class="link" href="#lifecycle-listener">7.29.1. Lifecycle listener</a></h4>
<div class="paragraph">
<p>You can create an implementation of
<em>org.wildfly.extension.core.management.client.ProcessStateListener</em>
which will be notified on running and runtime configuration state
changes thus enabling the developer to react to those changes.</p>
</div>
<div class="paragraph">
<p>In order to use this feature you need to create your own module then
configure and deploy it using the core management subsystem.</p>
</div>
<div class="paragraph">
<p>For example let&#8217;s create a simple listener :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"> <span class="directive">public</span> <span class="type">class</span> <span class="class">SimpleListener</span> <span class="directive">implements</span> ProcessStateListener {
<span class="error"> </span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">private</span> <span class="predefined-type">File</span> file;
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">private</span> <span class="predefined-type">FileWriter</span> fileWriter;
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">private</span> ProcessStateListenerInitParameters parameters;
<span class="error"> </span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="annotation">@Override</span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">public</span> <span class="type">void</span> init(ProcessStateListenerInitParameters parameters) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="local-variable">this</span>.parameters = parameters;
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="local-variable">this</span>.file = <span class="keyword">new</span> <span class="predefined-type">File</span>(parameters.getInitProperties().get(<span class="string"><span class="delimiter">&quot;</span><span class="content">file</span><span class="delimiter">&quot;</span></span>));
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="keyword">try</span> {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> fileWriter = <span class="keyword">new</span> <span class="predefined-type">FileWriter</span>(file, <span class="predefined-constant">true</span>);
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> } <span class="keyword">catch</span> (<span class="exception">IOException</span> e) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> e.printStackTrace();
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="annotation">@Override</span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">public</span> <span class="type">void</span> cleanup() {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="keyword">try</span> {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> fileWriter.close();
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> } <span class="keyword">catch</span> (<span class="exception">IOException</span> e) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> e.printStackTrace();
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> } <span class="keyword">finally</span> {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> fileWriter = <span class="predefined-constant">null</span>;
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="annotation">@Override</span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">public</span> <span class="type">void</span> runtimeConfigurationStateChanged(RuntimeConfigurationStateChangeEvent evt) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="keyword">try</span> {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> fileWriter.write(<span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">&quot;</span><span class="content">%s %s %s %s</span><span class="char">\n</span><span class="delimiter">&quot;</span></span>, parameters.getProcessType(), parameters.getRunningMode(), evt.getOldState(), evt.getNewState()));
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> } <span class="keyword">catch</span> (<span class="exception">IOException</span> e) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> e.printStackTrace();
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="annotation">@Override</span>
<span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="directive">public</span> <span class="type">void</span> runningStateChanged(RunningStateChangeEvent evt) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> <span class="keyword">try</span> {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> fileWriter.write(<span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">&quot;</span><span class="content">%s %s %s %s</span><span class="char">\n</span><span class="delimiter">&quot;</span></span>, parameters.getProcessType(), parameters.getRunningMode(), evt.getOldState(), evt.getNewState()));
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> } <span class="keyword">catch</span> (<span class="exception">IOException</span> e) {
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> e.printStackTrace();
<span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span><span class="error"> </span> }
<span class="error"> </span><span class="error"> </span><span class="error"> </span> }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To compile it you need to depend on the
<em>org.wildfly.core:wildfly-core-management-client</em> maven module. Now
let&#8217;s add the module to the wildfly modules :</p>
</div>
<div class="literalblock">
<div class="content">
<pre>module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/home/ehsavoie/dev/demo/simple-listener/target/simple-process-state-listener.jar</pre>
</div>
</div>
<div class="paragraph">
<p>Now we can register or listener :</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/subsystem=core-management/process-state-listener=simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener, properties={file=/home/wildfly/tmp/events.txt})</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuration-changes"><a class="anchor" href="#configuration-changes"></a><a class="link" href="#configuration-changes">7.29.2. Configuration changes</a></h4>
<div class="paragraph">
<p>You can use the core management subsystem to enable and configure an
<strong>in-memory</strong> history of the last configuration changes.<br>
For example to track the last 5 configuration changes let&#8217;s active this
:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/subsystem=core-management/service=configuration-changes:add(max-history=5)</pre>
</div>
</div>
<div class="paragraph">
<p>Now we can list the last configuration changes :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=core-management/service=configuration-changes:list-changes()
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [{
        &quot;operation-date&quot; =&gt; &quot;2016-12-05T11:05:12.867Z&quot;,
        &quot;access-mechanism&quot; =&gt; &quot;NATIVE&quot;,
        &quot;remote-address&quot; =&gt; &quot;/127.0.0.1&quot;,
        &quot;outcome&quot; =&gt; &quot;success&quot;,
        &quot;operations&quot; =&gt; [{
            &quot;address&quot; =&gt; [
                (&quot;subsystem&quot; =&gt; &quot;core-management&quot;),
                (&quot;service&quot; =&gt; &quot;configuration-changes&quot;)
            ],
            &quot;operation&quot; =&gt; &quot;add&quot;,
            &quot;max-history&quot; =&gt; 5,
            &quot;operation-headers&quot; =&gt; {
                &quot;caller-type&quot; =&gt; &quot;user&quot;,
                &quot;access-mechanism&quot; =&gt; &quot;NATIVE&quot;
            }
        }]
    }]
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="JAXRS"><a class="anchor" href="#JAXRS"></a><a class="link" href="#JAXRS">7.29.3. JAXRS Subsystem Configuration</a></h4>
<div class="paragraph">
<p>The <code>jaxrs</code> subsystem represents <a href="https://projects.eclipse.org/projects/ee4j.jaxrs">Jakarta RESTful Web Services</a>.
<a href="https://resteasy.github.io">RESTEasy</a> is the implementation.</p>
</div>
<div class="sect4">
<h5 id="required-extension"><a class="anchor" href="#required-extension"></a><a class="link" href="#required-extension">Required Extension:</a></h5>
<div class="paragraph">
<p>The required extension is in the module <code>org.jboss.as.jaxrs</code>. In most cases the extension should be present. However, if it
is not you can add it with CLI.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>/extension=org.jboss.as.jaxrs:add</code></pre>
</div>
</div>
<div class="paragraph">
<p>This adds the following configuration entry:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;extension</span> <span class="attribute-name">module</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.jboss.as.jaxrs</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="basic-subsystem-configuration-example"><a class="anchor" href="#basic-subsystem-configuration-example"></a><a class="link" href="#basic-subsystem-configuration-example">Basic Subsystem Configuration Example:</a></h5>
<div class="paragraph">
<p>By default the <code>jaxrs</code> subsystem is empty which results in default configuration values being used.</p>
</div>
<div class="paragraph">
<p>This can be changed with a management client such as the CLI or the web console. You can get detailed information about the
"Configuration switches" in section 3.5 of the <a href="https://resteasy.dev/docs">RESTEasy User Guide</a>.</p>
</div>
<div class="paragraph">
<p>An example configuring the subsystem with the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>/subsystem=jaxrs:write-attribute(name=resteasy-add-charset, value=true)
/subsystem=jaxrs:write-attribute(name=resteasy-gzip-max-input, value=17)
/subsystem=jaxrs:write-attribute(name=resteasy-gzip-max-input, value=17)
/subsystem=jaxrs:write-attribute(name=resteasy-jndi-resources, value=[&quot;java:global/jaxrsnoap/EJB_Resource1&quot;, &quot;java:global/jaxrsnoap/EJB_Resource2&quot;])
/subsystem=jaxrs:write-attribute(name=resteasy-language-mappings, value={&quot;es&quot;=&quot;es&quot;, &quot;fr&quot;=&quot;fr&quot;, &quot;en&quot;=&quot;en-US&quot;})
/subsystem=jaxrs:write-attribute(name=resteasy-media-type-param-mapping, value=mt)
/subsystem=jaxrs:write-attribute(name=resteasy-providers, value=[&quot;com.bluemonkey.reader&quot;, &quot;com.bluemonkey.writer&quot;])</code></pre>
</div>
</div>
<div class="paragraph">
<p>This generates the following XML configuration.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:jaxrs:2.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;resteasy-add-charset&gt;</span>true<span class="tag">&lt;/resteasy-add-charset&gt;</span>
    <span class="tag">&lt;resteasy-gzip-max-input&gt;</span>17<span class="tag">&lt;/resteasy-gzip-max-input&gt;</span>
    <span class="tag">&lt;resteasy-jndi-resources&gt;</span>
        <span class="tag">&lt;jndi&gt;</span>
            java:global/jaxrsnoap/EJB_Resource1
        <span class="tag">&lt;/jndi&gt;</span>
        <span class="tag">&lt;jndi&gt;</span>
            java:global/jaxrsnoap/EJB_Resource2
        <span class="tag">&lt;/jndi&gt;</span>
    <span class="tag">&lt;/resteasy-jndi-resources&gt;</span>
    <span class="tag">&lt;resteasy-language-mappings&gt;</span>
        <span class="tag">&lt;entry</span> <span class="attribute-name">key</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">es</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            es
        <span class="tag">&lt;/entry&gt;</span>
        <span class="tag">&lt;entry</span> <span class="attribute-name">key</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">fr</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            fr
        <span class="tag">&lt;/entry&gt;</span>
        <span class="tag">&lt;entry</span> <span class="attribute-name">key</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            en-US
        <span class="tag">&lt;/entry&gt;</span>
    <span class="tag">&lt;/resteasy-language-mappings&gt;</span>
    <span class="tag">&lt;resteasy-media-type-param-mapping&gt;</span>mt<span class="tag">&lt;/resteasy-media-type-param-mapping&gt;</span>
    <span class="tag">&lt;resteasy-providers&gt;</span>
        <span class="tag">&lt;class&gt;</span>
            com.bluemonkey.reader
        <span class="tag">&lt;/class&gt;</span>
        <span class="tag">&lt;class&gt;</span>
            com.bluemonkey.writer
        <span class="tag">&lt;/class&gt;</span>
    <span class="tag">&lt;/resteasy-providers&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The use of hyphens is a WildFly convention. The hyphens are translated into periods before
the parameters are passed into RESTEasy so that they conform to the RESTEasy parameter names.</p>
</div>
<div class="paragraph">
<p>For a discussion of the various parameters, see the RESTEasy User Guide.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
One important thing to understand is that these parameters are global. That is, they  apply to all deployments.
Since these parameters are global, the classes referred to in "resteasy.providers" and "resteasy.disable.providers"
must be available to all deployments. In practice, then, they are meant to enable
or disable RESTEasy providers. Note that they can be used in conjunction with
"resteasy-use-builtin-providers" to tailor a set of available providers.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Another important fact is that once parameters are changed via some management interface the changes require
           a redeployment of any applications previously deployed.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
RESTEasy has introduced a new treatment of <code>jakarta.ws.rs.WebApplicationException</code>&apos;s thrown by a
Jakarta REST client or MicroProfile REST Client running inside a RESTful resource, in which the embedded
<code>jakarta.ws.rs.core.Response</code> is "sanitized" before being returned to prevent the risk of information leaking from a
third party. The original behavior can be restored by setting the parameter
"resteasy.original.webapplicationexception.behavior" to "true". See the <a href="https://resteasy.dev/docs">RESTEasy User Guide</a>
chapter "Resteasy WebApplicationExceptions" for more information.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Elytron_OIDC_Client"><a class="anchor" href="#Elytron_OIDC_Client"></a><a class="link" href="#Elytron_OIDC_Client">7.30. Elytron OpenID Connect Client Subsystem Configuration</a></h3>
<div class="paragraph">
<p>The ability to secure applications using <a href="https://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</a> is
provided by the <em>elytron-oidc-client</em> subsystem.</p>
</div>
<div class="sect3">
<h4 id="subsystem-configuration-elytron-oidc-client"><a class="anchor" href="#subsystem-configuration-elytron-oidc-client"></a><a class="link" href="#subsystem-configuration-elytron-oidc-client">7.30.1. Subsystem</a></h4>
<div class="paragraph">
<p>The <em>elytron-oidc-client</em> subsystem is included in the default configuration. If not present, the subsystem can be
added using the following CLI commands.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /extension=org.wildfly.extension.elytron-oidc-client:add

[standalone@localhost:9990 /] /subsystem=elytron-oidc-client:add

[standalone@localhost:9990 /] reload</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuration-8"><a class="anchor" href="#configuration-8"></a><a class="link" href="#configuration-8">7.30.2. Configuration</a></h4>
<div class="paragraph">
<p>By default, the <em>elytron-oidc-client</em> subsystem does not contain any configured resources or attributes.</p>
</div>
<div class="paragraph">
<p>The configuration required to secure an application with OpenID Connect can either be provided within the
application itself or within the <em>elytron-oidc-client</em> subsystem.</p>
</div>
<div class="sect4">
<h5 id="deployment-configuration"><a class="anchor" href="#deployment-configuration"></a><a class="link" href="#deployment-configuration">Deployment Configuration</a></h5>
<div class="paragraph">
<p>The configuration required to secure an application with OpenID Connect can be specified in the deployment.</p>
</div>
<div class="paragraph">
<p>The first step is to create an <code>oidc.json</code> configuration file in the <code>WEB-INF</code> directory of the application.
The second step is to set the <code>auth-method</code> to <code>OIDC</code> in the application&#8217;s <code>web.xml</code> file.</p>
</div>
<div class="paragraph">
<p>Here is an example of an <code>oidc.json</code> configuration file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
  &quot;client-id&quot; : &quot;customer-portal&quot;,
  &quot;provider-url&quot; : &quot;http://localhost:8180/auth/realms/demo&quot;,
  &quot;ssl-required&quot; : &quot;external&quot;,
  &quot;use-resource-role-mappings&quot; : false,
  &quot;enable-cors&quot; : true,
  &quot;cors-max-age&quot; : 1000,
  &quot;cors-allowed-methods&quot; : &quot;POST, PUT, DELETE, GET&quot;,
  &quot;cors-exposed-headers&quot; : &quot;WWW-Authenticate, My-custom-exposed-Header&quot;,
  &quot;enable-basic-auth&quot; : false,
  &quot;expose-token&quot; : true,
  &quot;verify-token-audience&quot; : true,
   &quot;credentials&quot; : {
      &quot;secret&quot; : &quot;234234-234234-234234&quot;
   },

   &quot;connection-pool-size&quot; : 20,
   &quot;socket-timeout-millis&quot;: 5000,
   &quot;connection-timeout-millis&quot;: 6000,
   &quot;connection-ttl-millis&quot;: 500,
   &quot;disable-trust-manager&quot;: false,
   &quot;allow-any-hostname&quot; : false,
   &quot;truststore&quot; : &quot;path/to/truststore.jks&quot;,
   &quot;truststore-password&quot; : &quot;geheim&quot;,
   &quot;client-keystore&quot; : &quot;path/to/client-keystore.jks&quot;,
   &quot;client-keystore-password&quot; : &quot;geheim&quot;,
   &quot;client-key-password&quot; : &quot;geheim&quot;,
   &quot;token-minimum-time-to-live&quot; : 10,
   &quot;min-time-between-jwks-requests&quot; : 10,
   &quot;public-key-cache-ttl&quot;: 86400,
   &quot;redirect-rewrite-rules&quot; : {
   &quot;^/wsmain/api/(.*)$&quot; : &quot;/api/$1&quot;
   }
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="subsystem-configuration"><a class="anchor" href="#subsystem-configuration"></a><a class="link" href="#subsystem-configuration">Subsystem Configuration</a></h5>
<div class="paragraph">
<p>Instead of adding configuration to your deployment to secure it with OpenID Connect as described in the
previous section, another option is to add configuration to the <em>elytron-oidc-client</em> subsystem instead.</p>
</div>
<div class="paragraph">
<p>The following example shows how to add configuration to the <em>elytron-oidc-client</em> subsystem.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:elytron-oidc-client:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;secure-deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">DEPLOYMENT_RUNTIME_NAME.war</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;client-id&gt;</span>customer-portal<span class="tag">&lt;/client-id&gt;</span>
        <span class="tag">&lt;provider-url&gt;</span>http://localhost:8180/auth/realms/demo<span class="tag">&lt;/provider-url&gt;</span>
        <span class="tag">&lt;ssl-required&gt;</span>external<span class="tag">&lt;/ssl-required&gt;</span>
        <span class="tag">&lt;credential</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">secret</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0aa31d98-e0aa-404c-b6e0-e771dba1e798</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/secure-deployment&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>secure-deployment</code> resource allows you to provide configuration for a specific deployment. In
the example above, the <code>secure-deployment</code> resource is providing the configuration that should be used
for the <code>DEPLOYMENT_RUNTIME_NAME.war</code> deployment, where <code>DEPLOYMENT_RUNTIME_NAME</code> corresponds to
the <code>runtime-name</code> for the deployment.</p>
</div>
<div class="paragraph">
<p>The various configuration options that can be specified in the <code>secure-deployment</code> configuration
correspond to the same options that can be specified in the <code>oidc.json</code> configuration that was
explained in the previous section.</p>
</div>
<div class="paragraph">
<p>If you have multiple applications that are being secured using the same OpenID provider,
the <code>provider</code> configuration can be defined separately as shown in the example below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:elytron-oidc-client:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;provider</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">keycloak</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;provider-url&gt;</span>http://localhost:8080/auth/realms/demo<span class="tag">&lt;/provider-url&gt;</span>
        <span class="tag">&lt;ssl-required&gt;</span>external<span class="tag">&lt;/ssl-required&gt;</span>
    <span class="tag">&lt;/realm&gt;</span>
    <span class="tag">&lt;secure-deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">customer-portal.war</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;provider&gt;</span>keycloak<span class="tag">&lt;/provider&gt;</span>
        <span class="tag">&lt;client-id&gt;</span>customer-portal<span class="tag">&lt;/client-id&gt;</span>
        <span class="tag">&lt;credential</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">secret</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0aa31d98-e0aa-404c-b6e0-e771dba1e798</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/secure-deployment&gt;</span>
    <span class="tag">&lt;secure-deployment</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">product-portal.war</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;provider&gt;</span>keycloak<span class="tag">&lt;/provider&gt;</span>
        <span class="tag">&lt;client-id&gt;</span>product-portal<span class="tag">&lt;/client-id&gt;</span>
        <span class="tag">&lt;credential</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">secret</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0aa31d98-e0aa-404c-b6e0-e771dba1e798</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;/secure-deployment&gt;</span>
<span class="tag">&lt;/subsystem&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="activation-4"><a class="anchor" href="#activation-4"></a><a class="link" href="#activation-4">Activation</a></h5>
<div class="paragraph">
<p>The <em>elytron-oidc-client</em> subsystem will scan deployments to detect if the <code>OIDC</code> authentication mechanism
is required for any web components (i.e., for each deployment, the subsystem will determine if OIDC configuration
has either been found within the deployment or if there is OIDC configuration for the deployment in the subsystem
configuration). If the subsystem detects that the <code>OIDC</code> mechanism is indeed required, the subsystem will
activate the authentication mechanism automatically. Otherwise, no activation will occur and deployment
will continue normally.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="virtual-security-2"><a class="anchor" href="#virtual-security-2"></a><a class="link" href="#virtual-security-2">7.30.3. Virtual Security</a></h4>
<div class="paragraph">
<p>The purpose of using OpenID Connect is to verify a user&#8217;s identity based on the authentication that&#8217;s been
performed by the OpenID provider. For this reason, OpenID Connect deployments do not depend on <code>security-domain</code>
resources that have been defined in the Elytron subsystem, like traditional deployments do. Instead,
the <em>elytron-oidc-client</em> subsystem will automatically create and make use of its own virtual security domain
across the deployment. No further managed configuration is required.</p>
</div>
</div>
<div class="sect3">
<h4 id="openid-providers"><a class="anchor" href="#openid-providers"></a><a class="link" href="#openid-providers">7.30.4. OpenID Providers</a></h4>
<div class="paragraph">
<p>The <code>provider-url</code> attribute in the <code>oidc.json</code> configuration and in the <em>elytron-oidc-client</em>
subsystem configuration allows you to specify the URL for the OpenID provider that you&#8217;d like to use.
For WildFly 25, the <em>elytron-oidc-client</em> subsystem has been tested with the Keycloak OpenID provider.
Other OpenID providers haven&#8217;t been extensively tested yet so the use of other OpenID providers should
be considered experimental for now and should not be used in a production environment yet. Proper support
for other OpenID providers will be added in a future WildFly release.</p>
</div>
</div>
<div class="sect3">
<h4 id="multi-tenancy-support"><a class="anchor" href="#multi-tenancy-support"></a><a class="link" href="#multi-tenancy-support">7.30.5. Multi-Tenancy Support</a></h4>
<div class="paragraph">
<p>In some cases, it might be desirable to secure an application using multiple <code>oidc.json</code> configuration files.
For example, you might want a different <code>oidc.json</code> file to be used depending on the request in order to authenticate
users from multiple Keycloak realms. The <em>elytron-oidc-client</em> subsystem makes it possible to use a custom configuration
resolver so you can define which configuration file to use for each request.</p>
</div>
<div class="paragraph">
<p>To make use of the multi-tenancy feature, you need to create a class that implements the
<code>org.wildfly.security.http.oidc.OidcClientConfigurationResolver</code> interface, as shown in the example below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">example</span>;

<span class="keyword">import</span> <span class="include">java.io.InputStream</span>;
<span class="keyword">import</span> <span class="include">java.util.HashMap</span>;
<span class="keyword">import</span> <span class="include">java.util.Map</span>;
<span class="keyword">import</span> <span class="include">java.util.concurrent.ConcurrentHashMap</span>;

<span class="keyword">import</span> <span class="include">org.wildfly.security.http.oidc.OidcClientConfiguration</span>;
<span class="keyword">import</span> <span class="include">org.wildfly.security.http.oidc.OidcClientConfigurationBuilder</span>;
<span class="keyword">import</span> <span class="include">org.wildfly.security.http.oidc.OidcClientConfigurationResolver</span>;
<span class="keyword">import</span> <span class="include">org.wildfly.security.http.oidc.OidcHttpFacade</span>;

<span class="directive">public</span> <span class="type">class</span> <span class="class">MyCustomConfigResolver</span> <span class="directive">implements</span> OidcClientConfigurationResolver {

    <span class="directive">private</span> <span class="directive">final</span> <span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, OidcClientConfiguration&gt; cache = <span class="keyword">new</span> <span class="predefined-type">ConcurrentHashMap</span>&lt;&gt;();

    <span class="annotation">@Override</span>
    <span class="directive">public</span> OidcClientConfiguration resolve(OidcHttpFacade.Request request) {
        <span class="predefined-type">String</span> path = request.getURI();
        <span class="predefined-type">String</span> realm = ... <span class="comment">// determine which Keycloak realm to use based on the request path</span>
        OidcClientConfiguration clientConfiguration = cache.get(realm);
        <span class="keyword">if</span> (clientConfiguration == <span class="predefined-constant">null</span>) {
            <span class="predefined-type">InputStream</span> is = getClass().getResourceAsStream(<span class="string"><span class="delimiter">&quot;</span><span class="content">/oidc-</span><span class="delimiter">&quot;</span></span> + realm + <span class="string"><span class="delimiter">&quot;</span><span class="content">.json</span><span class="delimiter">&quot;</span></span>); <span class="comment">// config to use based on the realm</span>
            clientConfiguration = OidcClientConfigurationBuilder.build(is);
            cache.put(realm, clientConfiguration);
        }
        <span class="keyword">return</span> clientConfiguration;
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once you&#8217;ve created your <code>OidcClientConfigurationResolver `, you can specify that you want to make
use of your custom configuration resolver by setting the `oidc.config.resolver</code> <code>context-param</code> in
your application&#8217;s <code>web.xml</code> file, as shown in the example below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;web-app&gt;</span>
    ...
    <span class="tag">&lt;context-param&gt;</span>
        <span class="tag">&lt;param-name&gt;</span>oidc.config.resolver<span class="tag">&lt;/param-name&gt;</span>
        <span class="tag">&lt;param-value&gt;</span>example.MyCustomConfigResolver<span class="tag">&lt;/param-value&gt;</span>
    <span class="tag">&lt;/context-param&gt;</span>
    ...
<span class="tag">&lt;/web-app&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Simple_configuration_subsystems"><a class="anchor" href="#Simple_configuration_subsystems"></a><a class="link" href="#Simple_configuration_subsystems">7.31. Simple configuration subsystems</a></h3>
<div class="paragraph">
<p>The following subsystems currently have no configuration beyond its root
element in the configuration</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:jdr:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:pojo:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:sar:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The presence of each of these turns on a piece of functionality:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jdr</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables the gathering of diagnostic data for use in remote
analysis of error conditions. Although the data is in a simple format
and could be useful to anyone, primarily useful for JBoss EAP
subscribers who would provide the data to Red Hat when requesting
support</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">pojo</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables the deployment of applications containing JBoss
Microcontainer services, as supported by previous versions of JBoss
Application Server</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">sar</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables the deployment of .SAR archives containing MBean services,
as supported by previous versions of JBoss Application Server</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Domain_Setup"><a class="anchor" href="#Domain_Setup"></a><a class="link" href="#Domain_Setup">8. Domain Setup</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>To run a group of servers as a managed domain you need to configure both
the domain controller and each host that joins the domain. This sections
focuses on the network configuration for the domain and host controller
components. For background information users are encouraged to review
the <a href="#Operating_modes">Operating modes</a> and
<a href="Management_Clients.html#src-557081_ManagementClients-ConfigurationFiles">Configuration
Files</a> sections.</p>
</div>
<div class="sect2">
<h3 id="domain-controller-configuration"><a class="anchor" href="#domain-controller-configuration"></a><a class="link" href="#domain-controller-configuration">8.1. Domain Controller Configuration</a></h3>
<div class="paragraph">
<p>The domain controller is the central government for a managed domain. A
domain controller configuration requires two steps:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A host needs to be configured to act as the Domain Controller for the
whole domain</p>
</li>
<li>
<p>The host must expose an addressable management interface binding for
the managed hosts to communicate with it</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Example IP Addresses</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
In this example the domain controller uses 192.168.0.101 and the host
controller 192.168.0.10
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Configuring a host to act as the Domain Controller is done through the
<code>domain-controller</code> declaration in <code>host.xml</code>. If it includes the
<code>&lt;local/&gt;</code> element, then this host will become the domain controller:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;domain-controller&gt;</span>
   <span class="tag">&lt;local</span><span class="tag">/&gt;</span>
<span class="tag">&lt;/domain-controller&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>A host acting as the Domain Controller <em>must</em> expose a management
interface on an address accessible to the other hosts in the domain.
Exposing an HTTP(S) management interface is not required, but is
recommended as it allows the Administration Console to work:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;management-interfaces&gt;</span>
    <span class="tag">&lt;native-interface</span> <span class="attribute-name">sasl-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-sasl-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;socket</span> <span class="attribute-name">interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">9999</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/native-interface&gt;</span>
    <span class="tag">&lt;http-interface</span> <span class="attribute-name">http-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-http-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;http-upgrade</span> <span class="attribute-name">enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">sasl-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-sasl-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;socket</span> <span class="attribute-name">interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.management.http.port:9990}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/http-interface&gt;</span>
<span class="tag">&lt;/management-interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The interface attributes above refer to a named interface declaration
later in the host.xml file. This interface declaration will be used to
resolve a corresponding network interface.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interfaces&gt;</span>
   <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">192.168.0.101</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;/interface&gt;</span>
<span class="tag">&lt;/interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>Please consult the chapter "Interface Configuration" for a more detailed
explanation on how to configure network interfaces.</p>
</div>
<div class="paragraph">
<p>Next by default the Domain Controller is configured to require
authentication so a user needs to be added that can be used by the secondary
Host Controller to connect.</p>
</div>
<div class="paragraph">
<p>Make use of the <code>add-user</code> utility to add a new user, for this example I
am adding a new user called "secondary".</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<code>add-user</code> MUST be run on the Domain Controller and NOT the
secondary Host Controller.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="host-controller-configuration"><a class="anchor" href="#host-controller-configuration"></a><a class="link" href="#host-controller-configuration">8.2. Host Controller Configuration</a></h3>
<div class="paragraph">
<p>Once the Domain Controller is configured correctly you can proceed with
any host that should join the domain. The Host Controller configuration
requires three steps:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The logical host name (within the domain) needs to be distinct</p>
</li>
<li>
<p>The Host Controller needs to know the Domain Controller IP address</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Provide a distinct, logical name for the host. In the following example
we simply name it "secondary":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;host</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:3.0</span><span class="delimiter">&quot;</span></span>
     <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secondary</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
[...]
<span class="tag">&lt;/host&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>If the <code>name</code> attribute is not set, the default name for the host will
be the value of the <code>jboss.host.name</code> system property. If that is not
set, the value of the <code>HOSTNAME</code> or <code>COMPUTERNAME</code> environment variable
will be used, one of which will be set on most operating systems. If
neither is set the name will be the value of
<code>InetAddress.getLocalHost().getHostName()</code>.</p>
</div>
<div class="paragraph">
<p>An <code>authentication-context</code> needs to be defined in the <code>elytron</code> subsystem
to contain the identity of the host controller.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:wildfly:elytron:15.0</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">final-providers</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">combined-providers</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">disallowed-providers</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">OracleUcrypto</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;authentication-client&gt;</span>
        <span class="tag">&lt;authentication-configuration</span> <span class="attribute-name">sasl-mechanism-selector</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">DIGEST-MD5</span><span class="delimiter">&quot;</span></span>
                                      <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hostAuthConfig</span><span class="delimiter">&quot;</span></span>
                                      <span class="attribute-name">authentication-name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secondary</span><span class="delimiter">&quot;</span></span>
                                      <span class="attribute-name">realm</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ManagementRealm</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;credential-reference</span> <span class="attribute-name">clear-text</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">host_us3r_password</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/authentication-configuration&gt;</span>
        <span class="tag">&lt;authentication-context</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hcAuthContext</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;match-rule</span> <span class="attribute-name">authentication-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hostAuthConfig</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/authentication-context&gt;</span>
    <span class="tag">&lt;/authentication-client&gt;</span>
....</code></pre>
</div>
</div>
<div class="paragraph">
<p>Tell it how to find the Domain Controller, so it can register itself with
the domain:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;domain-controller&gt;</span>
   <span class="tag">&lt;remote</span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">remote</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">host</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">192.168.0.101</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">9999</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">authentication-context</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hcAuthContext</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/domain-controller&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Since we have also exposed the HTTP management interface we could also
use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;domain-controller&gt;</span>
   <span class="tag">&lt;remote</span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http-remoting</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">host</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">192.168.0.101</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">9990</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">username</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secondary</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">authentication-context</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hcAuthContext</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/domain-controller&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The name of each host needs to be unique when registering with the
Domain Controller, however the username does not - using the username
attribute allows the same account to be used by multiple hosts if this
makes sense in your environment.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="ignoring-domain-wide-resources"><a class="anchor" href="#ignoring-domain-wide-resources"></a><a class="link" href="#ignoring-domain-wide-resources">8.2.1. Ignoring domain wide resources</a></h4>
<div class="paragraph">
<p>WildFly 10 and later make it easy for secondary Host Controllers to "ignore"
parts of the domain wide configuration. What does the mean and why is it
useful?</p>
</div>
<div class="paragraph">
<p>One of the responsibilities of the Domain Controller is ensuring that
all running Host Controllers have a consistent local copy of the domain
wide configuration (i.e. those resources whose address does not begin
with <code>/host=*</code>, i.e. those that are persisted in <code>domain.xml</code>. Having
that local copy allows a user to do the following things:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Ask the secondary Host Controller to launch its already configured servers, even if the
Domain Controller is not running.</p>
</li>
<li>
<p>Configured new servers, using different server groups from those
current running, and ask the secondary Host Controller to launch them, even if the Domain
Controller is not running.</p>
</li>
<li>
<p>Reconfigure the secondary Host Controller to act as the Domain Controller, allowing it to
take over as the Domain Controller if the previous Domain Controller has failed or been shut
down.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>However, of these three things only the latter two require that the
secondary Host Controller maintain a <em>complete</em> copy of the domain wide configuration. The
first only requires the secondary Host Controller to have the <em>portion</em> of the domain wide
configuration that is relevant to its current servers. And the first use
case is the most common one. A secondary Host Controller that is only meant to support the
first use case can safely "ignore" portions of the domain wide
configuration. And there are benefits to ignoring some resources:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If a server group is ignored, and the deployments mapped to that
server group aren&#8217;t mapped to other non-ignored groups, then the secondary Host Controller
does not need to pull down a copy of the deployment content from the
Domain Controller. That can save disk space on the secondary Host Controller, improve the speed of
starting new hosts and reduce network traffic.</p>
</li>
<li>
<p>WildFly supports "mixed domains" where a later version Domain
Controller can manage secondary Host Controllers running previous versions. But those
"legacy" secondary Host Controllers cannot understand configuration resources, attributes
and operations introduced in newer versions. So any attempt to use newer
things in the domain wide configuration will fail unless the legacy
secondary Host Controllers are ignoring the relevant resources. But ignoring resources will
allow the legacy secondary Host Controllers to work fine managing servers using profiles
without new concepts, while other hosts can run servers with profiles
that take advantage of the latest features.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Prior to WildFly 10, a secondary Host Controller could be configured to ignore some
resources, but the mechanism was not particularly user friendly:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The resources to be ignored had to be listed in a fair amount of
detail in each host&#8217;s configuration.</p>
</li>
<li>
<p>If a new resource is added and needs to be ignored, then <strong>each</strong> host
that needs to ignore that must be updated to record that.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Starting with WildFly 10, this kind of detailed configuration is no
longer required. Instead, with the standard versions of <code>host.xml</code>, the
secondary Host Controller will behave as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If the secondary Host Controller was started with the <code>--backup</code> command line parameter,
the behavior will be the same as releases prior to 10; i.e. only
resources specifically configured to be ignored will be ignored.</p>
</li>
<li>
<p>Otherwise, the secondary Host Controller will "ignore unused resources".</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>What does "ignoring unused resources" mean?</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Any server-group that is not referenced by one of the host&#8217;s
server-config resources is ignored.</p>
</li>
<li>
<p>Any profile that is not referenced by a non-ignored server-group,
either directly or indirectly via the profile resource&#8217;s 'include'
attribute, is ignored</p>
</li>
<li>
<p>Any socket-binding-group that is not directly referenced by one of the
host&#8217;s server-config resources, or referenced by a non-ignored
server-group, is ignored</p>
</li>
<li>
<p>Extension resources will not be automatically ignored, even if no
non-ignored profile uses the extension. Ignoring an extension requires
explicit configuration. Perhaps in a future release extensions will be
explicitly ignored.</p>
</li>
<li>
<p>If a change is made to the secondary Host Controller host&#8217;s configuration or to the domain
wide configuration that reduces the set of ignored resources, then as
part of handling that change the secondary Host Controller will contact the Domain Controller to pull
down the missing pieces of configuration and will integrate those pieces
in its local copy of the management model. Examples of such changes
include adding a new server-config that references a previously ignored
server-group or socket-binding-group, changing the server-group or
socket-binding-group assigned to a server-config, changing the profile
or socket-binding-group assigned to a non-ignored server-group, or
adding a profile or socket-binding-group to the set of those included
directly or indirectly by a non-ignored profile or socket-binding-group.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The default behavior can be changed, either to always ignore unused
resources, even if <code>--backup</code> is used, or to not ignore unused
resources, by updating the domain-controller element in the <code>host-xml</code>
file and setting the <code>ignore-unused-configuration</code> attribute:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;domain-controller&gt;</span>
    <span class="tag">&lt;remote</span> <span class="attribute-name">authentication-context</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hcAuthContext</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">ignore-unused-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;discovery-options&gt;</span>
            <span class="tag">&lt;static-discovery</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">primary</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.protocol:remote}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">host</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.address}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.port:9999}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/discovery-options&gt;</span>
    <span class="tag">&lt;/remote&gt;</span>
<span class="tag">&lt;/domain-controller&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The "ignore unused resources" behavior can be used in combination with
the pre-WildFly 10 detailed specification of what to ignore. If that is
done both the unused resources and the explicitly declared resources
will be ignored. Here&#8217;s an example of such a configuration, one where
the secondary Host Controller cannot use the "org.example.foo" extension that has been
installed on the Domain Controller and on some secondary Host Controllers, but not this one:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;domain-controller&gt;</span>
    <span class="tag">&lt;remote</span> <span class="attribute-name">authentication-context</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hcAuthContext</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">ignore-unused-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;ignored-resources</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">extension</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;instance</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">org.example.foo</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/ignored-resources&gt;</span>
        <span class="tag">&lt;discovery-options&gt;</span>
            <span class="tag">&lt;static-discovery</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">primary</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.protocol:remote}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">host</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.address}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.domain.primary.port:9999}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/discovery-options&gt;</span>
    <span class="tag">&lt;/remote&gt;</span>
<span class="tag">&lt;/domain-controller&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="server-groups"><a class="anchor" href="#server-groups"></a><a class="link" href="#server-groups">8.3. Server groups</a></h3>
<div class="paragraph">
<p>The Domain Controller defines one or more server groups and associates
each of these with a profile and a socket binding group, and also:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;server-groups&gt;</span>
    <span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">512m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
           <span class="tag">&lt;permgen</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">128m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">128m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/jvm&gt;</span>
        <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/server-group&gt;</span>
    <span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bigger</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">512m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/jvm&gt;</span>
        <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bigger-sockets</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/server-group&gt;</span>
<span class="tag">&lt;/server-groups&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/domain.xml)~</p>
</div>
<div class="paragraph">
<p>The Domain Controller also defines the socket binding groups and the
profiles. The socket binding groups define the default socket bindings
that are used:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;socket-binding-groups&gt;</span>
    <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">8080</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        [...]
    <span class="tag">&lt;/socket-binding-group&gt;</span>
    <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bigger-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">include</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">unique-to-bigger</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">8123</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/socket-binding-group&gt;</span>
<span class="tag">&lt;/socket-binding-groups&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/domain.xml)~<br>
In this example the <code>bigger-sockets</code> group includes all the socket
bindings defined in the <code>standard-sockets</code> groups and then defines an
extra socket binding of its own.</p>
</div>
<div class="paragraph">
<p>A profile is a collection of subsystems, and these subsystems are what
implement the functionality people expect of an application server.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;profiles&gt;</span>
    <span class="tag">&lt;profile</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:web:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;connector</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">scheme</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">HTTP/1.1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            [...]
        <span class="tag">&lt;/subsystem&gt;</span>
        <span class="error">&lt;</span>\!-\- The rest of the subsystems here \--<span class="error">&gt;</span>
        [...]
    <span class="tag">&lt;/profile&gt;</span>
    <span class="tag">&lt;profile</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bigger</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:web:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;connector</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">scheme</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">protocol</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">HTTP/1.1</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">socket-binding</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            [...]
        <span class="tag">&lt;/subsystem&gt;</span>
        <span class="error">&lt;</span>\!-\- The same subsystems as defined by 'default' here \--<span class="error">&gt;</span>
        [...]
        <span class="tag">&lt;subsystem</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:jboss:domain:fictional-example:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;socket-to-use</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">unique-to-bigger</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/subsystem&gt;</span>
    <span class="tag">&lt;/profile&gt;</span>
<span class="tag">&lt;/profiles&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/domain.xml)~<br>
Here we have two profiles. The <code>bigger</code> profile contains all the same
subsystems as the <code>default</code> profile (although the parameters for the
various subsystems could be different in each profile), and adds the
<code>fictional-example</code> subsystem which references the <code>unique-to-bigger</code>
socket binding.</p>
</div>
</div>
<div class="sect2">
<h3 id="servers"><a class="anchor" href="#servers"></a><a class="link" href="#servers">8.4. Servers</a></h3>
<div class="paragraph">
<p>The Host Controller defines one or more servers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;servers&gt;</span>
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-one</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="error">&lt;</span>\!-\- server-one inherits the default socket-group declared in the server-group \--<span class="error">&gt;</span>
        <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/server&gt;</span>
 
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-two</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-start</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port-offset</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">150</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">256m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
        <span class="tag">&lt;/jvm&gt;</span>
    <span class="tag">&lt;/server&gt;</span>
 
    <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-three</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-start</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">bigger-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port-offset</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">250</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/server&gt;</span>
<span class="tag">&lt;/servers&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p><code>server-one</code> and <code>server-two</code> both are associated with
<code>main-server-group</code> so that means they both run the subsystems defined
by the <code>default</code> profile, and have the socket bindings defined by the
<code>standard-sockets</code> socket binding group. Since all the servers defined
by a host will be run on the same physical host we would get port
conflicts unless we used
<code>&lt;socket-binding-group ref="standard-sockets" port-offset="150"/&gt;</code> for
<code>server-two</code>. This means that <code>server-two</code> will use the socket bindings
defined by <code>standard-sockets</code> but it will add <code>150</code> to each port number
defined, so the value used for <code>http</code> will be <code>8230</code> for <code>server-two</code>.</p>
</div>
<div class="paragraph">
<p><code>server-three</code> will not be started due to its <code>auto-start="false"</code>. The
default value if no <code>auto-start</code> is given is <code>true</code> so both <code>server-one</code>
and <code>server-two</code> will be started when the host controller is started.
<code>server-three</code> belongs to <code>other-server-group</code>, so if its <code>auto-start</code>
were changed to <code>true</code> it would start up using the subsystems from the
<code>bigger</code> profile, and it would use the <code>bigger-sockets</code> socket binding
group.</p>
</div>
<div class="sect3">
<h4 id="jvm"><a class="anchor" href="#jvm"></a><a class="link" href="#jvm">8.4.1. JVM</a></h4>
<div class="paragraph">
<p>The Host Controller contains the main <code>jvm</code> definitions with arguments:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;jvms&gt;</span>
    <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">128m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/jvm&gt;</span>
<span class="tag">&lt;/jvms&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~<br>
From the preceding examples we can see that we also had a <code>jvm</code>
reference at server group level in the Domain Controller. The jvm&#8217;s name
<strong>must</strong> match one of the definitions in the Host Controller. The values
supplied at Domain Controller and Host Controller level are combined,
with the Host Controller taking precedence if the same parameter is
given in both places.</p>
</div>
<div class="paragraph">
<p>Finally, as seen, we can also override the <code>jvm</code> at server level. Again,
the jvm&#8217;s name <strong>must</strong> match one of the definitions in the Host Controller.
The values are combined with the ones coming in from Domain
Controller and Host Controller level, this time the server definition
takes precedence if the same parameter is given in all places.</p>
</div>
<div class="paragraph">
<p>Following these rules the jvm parameters to start each server would be</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Server</th>
<th class="tableblock halign-left valign-top">JVM parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">server-one</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-Xms64m -Xmx128m</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">server-two</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-Xms64m -Xmx256m</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">server-three</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-Xms64m -Xmx128m</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Management_tasks"><a class="anchor" href="#Management_tasks"></a><a class="link" href="#Management_tasks">9. Management tasks</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="Command_line_parameters"><a class="anchor" href="#Command_line_parameters"></a><a class="link" href="#Command_line_parameters">9.1. Command line parameters</a></h3>
<div class="paragraph">
<p>To start up a WildFly managed domain, execute the
<code>$JBOSS_HOME/bin/domain.sh</code> script. To start up a standalone server,
execute the <code>$JBOSS_HOME/bin/standalone.sh</code>. With no arguments, the
default configuration is used. You can override the default
configuration by providing arguments on the command line, or in your
calling script.</p>
</div>
<div class="sect3">
<h4 id="system-properties-2"><a class="anchor" href="#system-properties-2"></a><a class="link" href="#system-properties-2">9.1.1. System properties</a></h4>
<div class="paragraph">
<p>To set a system property, pass its new value using the standard jvm
<code>-Dkey=value</code> options:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$JBOSS_HOME/bin/standalone.sh -Djboss.home.dir=some/location/wildFly \
    -Djboss.server.config.dir=some/location/wildFly/custom-standalone</code></pre>
</div>
</div>
<div class="paragraph">
<p>This command starts up a standalone server instance using a non-standard
AS home directory and a custom configuration directory. For specific
information about system properties, refer to the definitions below.</p>
</div>
<div class="paragraph">
<p>Instead of passing the parameters directly, you can put them into a
properties file, and pass the properties file to the script, as in the
two examples below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$JBOSS_HOME/bin/domain.sh --properties=/some/location/jboss.properties
$JBOSS_HOME/bin/domain.sh -P=/some/location/jboss.properties</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note however, that properties set this way are not processed as part of
JVM launch. They are processed early in the boot process, but this
mechanism should not be used for setting properties that control JVM
behavior (e.g. java.net.perferIPv4Stack) or the behavior of the JBoss
Modules classloading system.</p>
</div>
<div class="paragraph">
<p>The syntax for passing in parameters and properties files is the same
regardless of whether you are running the <code>domain.sh</code>, <code>standalone.sh</code>,
or the Microsoft Windows scripts <code>domain.bat</code> or <code>standalone.bat</code>.</p>
</div>
<div class="paragraph">
<p>The properties file is a standard Java property file containing
<code>key=value</code> pairs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>jboss.home.dir=/some/location/wildFly
jboss.domain.config.dir=/some/location/wildFly/custom-domain</code></pre>
</div>
</div>
<div class="paragraph">
<p>System properties can also be set via the xml configuration files. Note
however that for a standalone server properties set this way will not be
set until the xml configuration is parsed and the commands created by
the parser have been executed. So this mechanism should not be used for
setting properties whose value needs to be set before this point.</p>
</div>
<div class="sect4">
<h5 id="controlling-filesystem-locations-with-system-properties"><a class="anchor" href="#controlling-filesystem-locations-with-system-properties"></a><a class="link" href="#controlling-filesystem-locations-with-system-properties">Controlling filesystem locations with system properties</a></h5>
<div class="paragraph">
<p>The standalone and the managed domain modes each use a default
configuration which expects various files and writable directories to
exist in standard locations. Each of these standard locations is
associated with a system property, which has a default value. To
override a system property, pass its new value using the one of the
mechanisms above. The locations which can be controlled via system
property are:</p>
</div>
<div class="sect5">
<h6 id="standalone"><a class="anchor" href="#standalone"></a><a class="link" href="#standalone">Standalone</a></h6>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">Usage</th>
<th class="tableblock halign-left valign-top">Default value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">java.ext.dirs</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The JDK extension directory paths</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">null</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.home.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The root directory of the WildFly installation.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set by
standalone.sh to $JBOSS_HOME</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.base.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The base directory for server content.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.home.dir/standalone</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.config.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The base configuration directory.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.base.dir/configuration</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.data.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used for persistent data file
storage.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.base.dir/data</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.log.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory containing the server.log file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.base.dir/log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.temp.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used for temporary file storage.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.base.dir/tmp</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.deploy.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used to store deployed content</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.server.data.dir/content</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="managed-domain-4"><a class="anchor" href="#managed-domain-4"></a><a class="link" href="#managed-domain-4">Managed Domain</a></h6>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">Usage</th>
<th class="tableblock halign-left valign-top">Default value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.home.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The root directory of the WildFly installation.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set by
domain.sh to $JBOSS_HOME</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The base directory for domain content.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.home.dir/domain</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.config.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The base configuration directory</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/configuration</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.data.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used for persistent data file
storage.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/data</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.log.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory containing the host-controller.log
and process-controller.log files</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/log</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.temp.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used for temporary file storage</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/tmp</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.deployment.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory used to store deployed
content</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/content</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.servers.dir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The directory containing the output for the
managed server instances</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jboss.domain.base.dir/servers</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="other-command-line-parameters"><a class="anchor" href="#other-command-line-parameters"></a><a class="link" href="#other-command-line-parameters">9.1.2. Other command line parameters</a></h4>
<div class="paragraph">
<p>The first acceptable format for command line arguments to the WildFly
launch scripts is</p>
</div>
<div class="literalblock">
<div class="content">
<pre>--name=value</pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the parameter name is a single character, it is prefixed by a single
'-' instead of two. Some parameters have both a long and short option.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>-x=value</pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$JBOSS_HOME/bin/standalone.sh -P=/some/location/jboss.properties</code></pre>
</div>
</div>
<div class="paragraph">
<p>For some command line arguments frequently used in previous major
releases of WildFly, replacing the "=" in the above examples with a
space is supported, for compatibility.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>-b 192.168.100.10</pre>
</div>
</div>
<div class="paragraph">
<p>If possible, use the <code>-x=value</code> syntax. New parameters will always
support this syntax.</p>
</div>
<div class="paragraph">
<p>The sections below describe the command line parameter names that are
available in standalone and domain mode.</p>
</div>
<div class="sect4">
<h5 id="standalone-1"><a class="anchor" href="#standalone-1"></a><a class="link" href="#standalone-1">Standalone</a></h5>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Default if absent</th>
<th class="tableblock halign-left valign-top">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--admin-only</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set the server&#8217;s running type to ADMIN_ONLY causing it
to open administrative interfaces and accept management requests but not
start other runtime services or accept end user requests.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config -c</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">standalone.xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted
to be relative to jboss.server.config.dir. The name of the configuration
file to use.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--read-only-server-config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted to
be relative to jboss.server.config.dir. This is similar to
--server-config but if this alternative is specified the server will not
overwrite the file when the management model is changed. However, a full
versioned history is maintained of the file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--graceful-startup</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Start the servers in gracefully, queuing or cleanly rejecting incoming requests until the server is fully started.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--git-repo</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">remote Git repository URL to use for configuration directory and content repository content or <code>local</code> if only a local repository is to be used.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--git-branch</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">master</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The Git branch or tag to be used. If a <code>tag</code> name is used then the future commits will go into the detached state.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--git-auth</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A URL to an Elytron configuration file containing the credentials to be used for connecting to the Git repository.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="managed-domain-1"><a class="anchor" href="#managed-domain-1"></a><a class="link" href="#managed-domain-1">Managed Domain</a></h5>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Default if absent</th>
<th class="tableblock halign-left valign-top">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--admin-only</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set the host controller&#8217;s running type to ADMIN_ONLY causing it to open
administrative interfaces and accept management requests but not start servers or, if this
host controller is the primary for the domain, accept incoming connections from secondary
host controllers.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--domain-config -c</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">domain.xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted to
be relative to jboss.domain.config.dir. The name of the domain wide
configuration file to use.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--read-only-domain-config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted to
be relative to jboss.domain.config.dir. This is similar to
--domain-config but if this alternative is specified the host
controller will not overwrite the file when the management model is
changed. However, a full versioned history is maintained of the file.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--host-config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">host.xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted to be
relative to jboss.domain.config.dir. The name of the host-specific
configuration file to use.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--read-only-host-config</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A relative path which is interpreted to be
relative to jboss.domain.config.dir. This is similar to --host-config
but if this alternative is specified the host controller will not
overwrite the file when the management model is changed. However, a full
versioned history is maintained of the file.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The following parameters take no value and are only usable on secondary host
controllers (i.e. hosts configured to connect to a <code>remote</code> domain
controller.)</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Function</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--backup</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Causes the secondary host controller to create and maintain a
local copy (domain.cached-remote.xml) of the domain configuration. If
ignore-unused-configuration is unset in host.xml,a complete copy of the
domain configuration will be stored locally, otherwise the configured
value of ignore-unused-configuration in host.xml will be used. (See
ignore-unused-configuration for more details.)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--cached-dc</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If the secondary host controller is unable to contact the
domain controller to get its configuration at boot, this option
will allow the secondary host controller to boot and become operational using
a previously cached copy of the domain configuration
(domain.cached-remote.xml.) If the cached configuration is not present,
this boot will fail. This file is created using one of the
following methods:- A previously successful connection to the
domain controller using --backup or --cached-dc.- Copying the domain
configuration from an alternative host to
domain/configuration/domain.cached-remote.xml.The unavailable
domain controller will be polled periodically for availability, and once
becoming available, the secondary host controller will reconnect to the
domain controller and synchronize the domain configuration. During
the interval the domain controller is unavailable, the secondary host
controller will not be able to make any modifications to the domain
configuration, but it may launch servers and handle requests to deployed
applications etc.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="common-parameters"><a class="anchor" href="#common-parameters"></a><a class="link" href="#common-parameters">Common parameters</a></h5>
<div class="paragraph">
<p>These parameters apply in both standalone or managed domain mode:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Function</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">-b=&lt;value&gt;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets system property jboss.bind.address to &lt;value&gt;. See
Controlling the Bind Address with -b for further details.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">-b&lt;name&gt;=&lt;value&gt;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets system property jboss.bind.address.&lt;name&gt; to
&lt;value&gt; where name can vary. See Controlling the Bind Address with -b
for further details.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">-u=&lt;value&gt;</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets system property jboss.default.multicast.address to
&lt;value&gt;. See Controlling the Default Multicast Address with -u for
further details.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--version -v -V</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prints the version of WildFly to standard output and
exits the JVM.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">--help-h</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Prints a help message explaining the options and exits the
JVM.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="controlling-the-bind-address"><a class="anchor" href="#controlling-the-bind-address"></a><a class="link" href="#controlling-the-bind-address">9.1.3. Controlling the Bind Address with -b</a></h4>
<div class="paragraph">
<p>WildFly binds sockets to the IP addresses and interfaces contained in
the <code>&lt;interfaces&gt;</code> elements in <code>standalone.xml</code>, <code>domain.xml</code> and
<code>host.xml</code>. (See
<a href="#interfaces">Interfaces</a>
and
<a href="#socket-bindings-and-socket-binding-groups">Socket
Bindings</a> for further information on these elements.) The standard
configurations that ship with WildFly includes two interface
configurations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interfaces&gt;</span>
    <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address.management:127.0.0.1}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/interface&gt;</span>
    <span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
       <span class="tag">&lt;inet-address</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.bind.address:127.0.0.1}</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
    <span class="tag">&lt;/interface&gt;</span>
<span class="tag">&lt;/interfaces&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Those configurations use the values of system properties
<code>jboss.bind.address.management</code> and <code>jboss.bind.address</code> if they are
set. If they are not set, 127.0.0.1 is used for each value.</p>
</div>
<div class="paragraph">
<p>As noted in
<a href="#common-parameters">Common
Parameters</a>, the AS supports the <code>-b</code> and <code>-b&lt;name&gt;</code> command line
switches. The only function of these switches is to set system
properties <code>jboss.bind.address</code> and <code>jboss.bind.address.&lt;name&gt;</code>
respectively. However, because of the way the standard WildFly
configuration files are set up, using the <code>-b</code> switches can indirectly
control how the AS binds sockets.</p>
</div>
<div class="paragraph">
<p><em>If your interface configurations match those shown above</em>, using this
as your launch command causes all sockets associated with interface
named "public" to be bound to <code>192.168.100.10</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$JBOSS_HOME/bin/standalone.sh -b=192.168.100.10</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the standard config files, public interfaces are those not associated
with server management. Public interfaces handle normal end-user
requests.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The interface named "public" is not inherently special. It is provided
as a convenience. You can name your interfaces to suit your environment.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To bind the public interfaces to all IPv4 addresses (the IPv4 wildcard
address), use the following syntax:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$JBOSS_HOME/bin/standalone.sh -b=0.0.0.0</pre>
</div>
</div>
<div class="paragraph">
<p>You can also bind the management interfaces, as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$JBOSS_HOME/bin/standalone.sh -bmanagement=192.168.100.10</pre>
</div>
</div>
<div class="paragraph">
<p>In the standard config files, management interfaces are those sockets
associated with server management, such as the socket used by the CLI,
the HTTP socket used by the admin console, and the JMX connector socket.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The <code>-b</code> switch only controls the interface bindings because the
standard config files that ship with WildFly sets things up that way. If
you change the <code>&lt;interfaces&gt;</code> section in your configuration to no longer
use the system properties controlled by <code>-b</code>, then setting <code>-b</code> in your
launch command will have no effect.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For example, this perfectly valid setting for the "public" interface
causes <code>-b</code> to have no effect on the "public" interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;interface</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">public</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
   <span class="tag">&lt;nic</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">eth0</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/interface&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The key point is <strong>the contents of the configuration files determine the
configuration. Settings like</strong> <code>-b</code> <strong>are not overrides of the
configuration files.</strong> They only provide a shorter syntax for setting a
system properties that may or may not be referenced in the configuration
files. They are provided as a convenience, and you can choose to modify
your configuration to ignore them.</p>
</div>
</div>
<div class="sect3">
<h4 id="controlling-the-default-multicast-address-with--u"><a class="anchor" href="#controlling-the-default-multicast-address-with--u"></a><a class="link" href="#controlling-the-default-multicast-address-with--u">9.1.4. Controlling the Default Multicast Address with -u</a></h4>
<div class="paragraph">
<p>WildFly may use multicast communication for some services, particularly
those involving high availability clustering. The multicast addresses
and ports used are configured using the <code>socket-binding</code> elements in
<code>standalone.xml</code> and <code>domain.xml</code>. (See
<a href="#socket-bindings-and-socket-binding-groups">Socket
Bindings</a> for further information on these elements.) The standard HA
configurations that ship with WildFly include two socket binding
configurations that use a default multicast address:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jgroups-mping</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">multicast-address</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.default.multicast.address:230.0.0.4}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">multicast-port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">45700</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;socket-binding</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jgroups-udp</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">55200</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">multicast-address</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${jboss.default.multicast.address:230.0.0.4}</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">multicast-port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">45688</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Those configurations use the values of system property
<code>jboss.default.multicast.address</code> if it is set. If it is not set,
<code>230.0.0.4</code> is used for each value. (The configuration may include other
socket bindings for multicast-based services that are not meant to use
the default multicast address; e.g. a binding the mod-cluster services
use to communicate on a separate address/port with Apache httpd
servers.)</p>
</div>
<div class="paragraph">
<p>As noted in
<a href="#common-parameters">Common Parameters</a>, the AS supports the <code>-u</code> command line switch. The only
function of this switch is to set system property <code>jboss.default.multicast.address</code>. However, because of the way the
standard AS configuration files are set up, using the <code>-u</code> switches can indirectly control how the AS uses multicast.</p>
</div>
<div class="paragraph">
<p><em>If your socket binding configurations match those shown above</em>, using
this as your launch command causes the service using those sockets
configurations to be communicate over multicast address <code>230.0.1.2</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$JBOSS_HOME/bin/standalone.sh -u=230.0.1.2</pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
As with the <code>-b</code> switch, the <code>-u</code> switch only controls the multicast
address used because the standard config files that ship with WildFly
sets things up that way. If you change the <code>&lt;socket-binding&gt;</code> sections
in your configuration to no longer use the system properties controlled
by <code>-u</code>, then setting <code>-u</code> in your launch command will have no effect.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Suspend"><a class="anchor" href="#Suspend"></a><a class="link" href="#Suspend">9.2. Suspend, Resume and Graceful shutdown</a></h3>
<div class="sect3">
<h4 id="core-concepts"><a class="anchor" href="#core-concepts"></a><a class="link" href="#core-concepts">9.2.1. Core Concepts</a></h4>
<div class="paragraph">
<p>WildFly introduces the ability to suspend and resume servers. This can
be combined with shutdown to enable the server to gracefully finish
processing all active requests and then shut down. When a server is
suspended it will immediately stop accepting new requests, but wait for
existing requests to complete. A suspended server can be resumed at any
point, and will begin processing requests immediately. Suspending and
resuming has no effect on deployment state (e.g. if a server is
suspended singleton Jakarta Enterprise Beans&#8217;s will not be destroyed). As of WildFly 11 it is
also possible to start a server in suspended mode which means it will
not accept requests until it has been resumed. Servers will also be
suspended during the boot process, so no requests will be accepted until
the startup process is 100% complete.</p>
</div>
<div class="paragraph">
<p>Suspend/Resume has no effect on management operations; management
operations can still be performed while a server is suspended. If you
wish to perform a management operation that will affect the operation of
the server you can suspend the server, perform the operation, and then
resume the server. This allows all requests to finish, and makes sure
that no requests are running while the management changes are taking
place.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If you perform a management operation while the server is suspended,
and the response to that operation includes the
<code>operation-requires-reload</code> or <code>operation-requires-restart</code> response
headers, then the operation will not take full effect until that
reload or restart is done. Simply resuming the server will not be
sufficient to cause the change to take effect.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>When a server is suspending it goes through four different states:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>RUNNING</strong> - The normal state, the server is accepting requests and
running normally</p>
</li>
<li>
<p><strong>PRE_SUSPEND</strong> - In PRE_SUSPEND the server will notify external parties
that it is about to suspend, for example mod_cluster will notify the
load balancer that the deployment is suspending. Requests are still
accepted in this phase.</p>
</li>
<li>
<p><strong>SUSPENDING</strong> - All new requests are rejected, and the server is
waiting for all active requests to finish. If there are no active
requests at suspend time this phase will be skipped.</p>
</li>
<li>
<p><strong>SUSPENDED</strong> - All requests have completed, and the server is
suspended.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="starting-suspended"><a class="anchor" href="#starting-suspended"></a><a class="link" href="#starting-suspended">9.2.2. Starting Suspended</a></h4>
<div class="paragraph">
<p>In order to start into suspended mode when using a standalone server you
need to add <strong>--start-mode=suspend</strong> to the command line. It is also
possible to specify the start-mode in the <strong>reload</strong> operation to cause
the server to reload into suspended mode (other possible values for
start-mode are <strong>normal</strong> and <strong>admin-only</strong>).</p>
</div>
<div class="paragraph">
<p>In domain mode servers can be started in suspended mode by passing the
<strong>suspend=true</strong> parameter to any command that causes a server to start,
restart or reload (e.g. :start-servers(suspend=true)).</p>
</div>
</div>
<div class="sect3">
<h4 id="the-request-controller-subsystem"><a class="anchor" href="#the-request-controller-subsystem"></a><a class="link" href="#the-request-controller-subsystem">9.2.3. The Request Controller Subsystem</a></h4>
<div class="paragraph">
<p>WildFly introduces a new subsystem called the Request Controller
Subsystem. This optional subsystem tracks all requests at their entry
point, which is how the graceful shutdown mechanism knows when all requests
are done. (It also allows you to provide a global limit on the total
number of running requests).</p>
</div>
<div class="paragraph">
<p>If this subsystem is not present suspend/resume will be limited. In
general things that happen in the PRE_SUSPEND phase will work as normal
(stopping message delivery, notifying the load balancer); however the
server will not wait for all requests to complete and instead will move
straight to SUSPENDED mode.</p>
</div>
<div class="paragraph">
<p>There is a small performance penalty associated with the request
controller subsystem (about on par with enabling statistics), so if you
do not require the suspend/resume functionality this subsystem can be
removed to get a small performance boost.</p>
</div>
</div>
<div class="sect3">
<h4 id="subsystem-integrations"><a class="anchor" href="#subsystem-integrations"></a><a class="link" href="#subsystem-integrations">9.2.4. Subsystem Integrations</a></h4>
<div class="paragraph">
<p>Suspend/Resume is a service provided by the WildFly platform that any
subsystem may choose to integrate with. Some subsystems integrate
directly with the suspend controller, while others integrate through the
request controller subsystem.</p>
</div>
<div class="paragraph">
<p>The following subsystems support graceful shutdown. Note that only
subsystems that provide an external entry point to the server need
graceful shutdown support. For example the Jakarta RESTful Web Services subsystem does not
require suspend/resume support as all access to Jakarta RESTful Web Services is through the
web connector.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Undertow</strong> - Undertow will wait for all requests to finish.</p>
</li>
<li>
<p><strong>mod_cluster</strong> - The mod_cluster subsystem will notify the load
balancer that the server is suspending in the PRE_SUSPEND phase.</p>
</li>
<li>
<p><strong>Jakarta Enterprise Beans</strong> - Jakarta Enterprise Beans will wait
for all remote Jakarta Enterprise Beans requests and MDB message
deliveries to finish. Delivery to MDB&#8217;s is stopped in the PRE_SUSPEND
phase. Jakarta Enterprise Beans timers are suspended, and missed timers will be activated
when the server is resumed.</p>
</li>
<li>
<p><strong>Batch</strong> - Batch jobs will be stopped at a checkpoint while the server
is suspending. They will be restarted from that checkpoint when the
server returns to running mode.</p>
</li>
<li>
<p><strong>EE Concurrency</strong> - The server will wait for all active jobs to finish.
All jobs that have already been queued will be skipped.</p>
</li>
<li>
<p><strong>Transactions</strong> - The transaction subsystem waits for all running
transactions to finish while the server is suspending. During that time
the server refuses to start any new transaction. But any in-flight
transaction will be serviced - e.g. the server will accept any
incoming remote call which carries the context of a transaction already
started at the suspending server.</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="transactions-and-Jakarta-Enterprise-Beans"><a class="anchor" href="#transactions-and-Jakarta-Enterprise-Beans"></a><a class="link" href="#transactions-and-Jakarta-Enterprise-Beans">Transactions and Jakarta Enterprise Beans</a></h5>
<div class="paragraph">
<p>When you work with Jakarta Enterprise Beans you have to enable the graceful shutdown
functionality by setting the attribute <code>enable-graceful-txn-shutdown</code> to
<code>true</code>. For example, in the ejb3 subsystem section of <code>standalone.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;enable-graceful-txn-shutdown</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>By <strong>default</strong> graceful shutdown is <strong>disabled</strong> for the ejb subsystem.
The reason for this is that the behavior might be unwelcome in cluster
environments, as the server notifies remote clients that the node is no
longer available for remote calls only after the transactions are
finished. During that brief window of time, the client of a cluster may
send a new request to a node that is shutting down and it will refuse the
request because it is not related to an existing transaction.
If this attribute <code>enable-graceful-txn-shutdown</code> is set to <code>false</code>, we
disable the graceful behavior and Jakarta Enterprise Beans clients will not attempt to invoke
the node when it suspends, regardless of active transactions.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="standalone-mode"><a class="anchor" href="#standalone-mode"></a><a class="link" href="#standalone-mode">9.2.5. Standalone Mode</a></h4>
<div class="paragraph">
<p>Suspend/Resume can be controlled via the following CLI operations
and commands in standalone mode:</p>
</div>
<div class="paragraph">
<p><code>:suspend(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p>Suspends the server. If the timeout is specified it will wait in the
SUSPENDING phase up to the specified number of seconds for all requests
to finish. If there is no timeout specified or the value is less than
zero it will wait indefinitely.</p>
</div>
<div class="paragraph">
<p><code>:resume</code></p>
</div>
<div class="paragraph">
<p>Resumes a previously suspended server. The server should be able to
begin serving requests immediately.</p>
</div>
<div class="paragraph">
<p><code>:read-attribute(name=suspend-state)</code></p>
</div>
<div class="paragraph">
<p>Returns the current suspend state of the server.</p>
</div>
<div class="paragraph">
<p><code>shutdown --suspend-timeout=x</code></p>
</div>
<div class="paragraph">
<p>If a timeout parameter is passed to the shutdown command then a graceful
shutdown will be performed. The server will be suspended, and will wait
in SUSPENDING state up to the specified number of seconds for all requests
to finish before shutting down. A timeout value of less than zero means
it will wait indefinitely.</p>
</div>
</div>
<div class="sect3">
<h4 id="domain-mode"><a class="anchor" href="#domain-mode"></a><a class="link" href="#domain-mode">9.2.6. Domain Mode</a></h4>
<div class="paragraph">
<p>Domain mode has similar operations as standalone mode, however they can be
applied at global, server group, server and host levels:</p>
</div>
<div class="paragraph">
<p><strong>Whole Domain</strong></p>
</div>
<div class="paragraph">
<p><code>:suspend-servers(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><code>:resume-servers</code></p>
</div>
<div class="paragraph">
<p><code>:stop-servers(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><strong>Server Group</strong></p>
</div>
<div class="paragraph">
<p><code>/server-group=main-server-group:suspend-servers(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><code>/server-group=main-server-group:resume-servers</code></p>
</div>
<div class="paragraph">
<p><code>/server-group=main-server-group:stop-servers(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><strong>Server</strong></p>
</div>
<div class="paragraph">
<p><code>/host=primary/server-config=server-one:suspend(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><code>/host=primary/server-config=server-one:resume</code></p>
</div>
<div class="paragraph">
<p><code>/host=primary/server-config=server-one:stop(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><strong>Host level</strong></p>
</div>
<div class="paragraph">
<p><code>/host=primary:suspend-servers(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p><code>/host=primary:resume-servers</code></p>
</div>
<div class="paragraph">
<p><code>/host=primary:shutdown(suspend-timeout=x)</code></p>
</div>
<div class="paragraph">
<p>Note that even though the host controller itself is being shut down, the suspend-timeout attribute for the shutdown operation at host level is applied to the servers only and not to the host controller itself.</p>
</div>
</div>
<div class="sect3">
<h4 id="graceful-shutdown-from-an-os-signal"><a class="anchor" href="#graceful-shutdown-from-an-os-signal"></a><a class="link" href="#graceful-shutdown-from-an-os-signal">9.2.7. Graceful Shutdown via an OS Signal</a></h4>
<div class="paragraph">
<p>If you use an OS signal like <code>TERM</code> to shut down your WildFly standalone server
process, e.g. via <code>kill -15 &lt;pid&gt;</code>, the WildFly server will shut down gracefully.
By default, the behavior will be analogous to a CLI <code>shutdown --suspend-timeout=0</code> command;
that is the process will not wait in SUSPENDING state for in-flight requests to
complete before proceeding to SUSPENDED state and then shutting down. A different
timeout can be configured by setting the <code>org.wildfly.sigterm.suspend.timeout</code>
system property. The value of the property should be an integer indicating the maximum
number of seconds to wait for in-flight requests to complete. A value of <code>-1</code> means
the server should wait indefinitely.</p>
</div>
<div class="paragraph">
<p>Graceful shutdown via an OS signal will not work if the server JVM is configured
to disable signal handling (i.e. with the <code>-Xrs</code> argument to java). It also won&#8217;t
work if the method used to terminate the process doesn&#8217;t result in a signal the
JVM can respond to (e.g. <code>kill -9</code>).</p>
</div>
<div class="paragraph">
<p>In a managed domain, Process Controller and Host Controller processes will not attempt
any sort of graceful shutdown in response to a signal. A domain mode server may, but
the proper way to control the lifecycle of a domain mode server process is via the
management API and its managing Host Controller, not via direct signals to the server
process.</p>
</div>
</div>
<div class="sect3">
<h4 id="non-graceful-startup"><a class="anchor" href="#non-graceful-startup"></a><a class="link" href="#non-graceful-startup">9.2.8. Non-graceful Startup</a></h4>
<div class="paragraph">
<p>By default, WildFly starts up gracefully, meaning that incoming requests are queued or cleanly rejected
until the server is ready to process them. In some instances, though, it may be desirable to allow the
server to begin to process requests at the earliest possible moment. One such example might be
when two deployed applications need to interact with one another during the deployment or
application startup. In one such scenario, Application A needs to make a REST request to
Application B to get information vital to its own startup. Under a graceful startup, the request
to Application B will block until the server is fully started. However, the server can&#8217;t fully
start, as Application A is waiting for data from Application B before its deploy/startup can
complete. In this situation, a deadlock occurs, and the server startup times out.</p>
</div>
<div class="paragraph">
<p>A non-graceful startup is intended to address this situation in that it will allow WildFly to
begin attempting to answer requests as soon as possible. In the scenario above, assuming
Application B has successfully deployed/started, Application A can also start immediately, as its
request will be fulfilled. Note, however, that a race condition can occur: if Application B is
not yet deployed (e.g., the deploy order is incorrect, or B has not finished starting), then
Application A may still fail to start since Application B is not available. WildFly users making
use of non-graceful startups must be aware of this and take steps to remedy those scenarios. With
a non-graceful startup, however, WildFly will no longer be the cause of a deployment failure in
such a configuration.</p>
</div>
<div class="paragraph">
<p>Some discussion here of how this relates to reloading and restarting, as well as to suspended starts, is
important. When reloading, the <code>ApplicationServerService</code> is stopped, and a new one started. It is equivalent
to if it was being started the first time: all the same stuff happens, but it happens faster because a lot of
classloading and static initialization doesn&#8217;t have to happen again. This includes honoring the value of
<code>graceful-startup</code>, so if the server was initially started non-gracefully, it will be reloaded in the same manner.</p>
</div>
<div class="paragraph">
<p>Restarting the server is similar. A restart means a new JVM, so all the initialization happens again, exactly
as it did on the first start. When restarting in domain mode, the Host Controller simply rereads the config
file and does the same thing it did the first time. In standalone, the restart is driven by <code>standalone.[sh|ps1|bat]</code>.
The running JVM exits with a specific exit code, which the script recognizes and starts a new server, using the
same parameters as the first start, so if you start a server non-gracefully, you will restart a server
non-gracefully.</p>
</div>
<div class="paragraph">
<p>Finally, there&#8217;s <code>start-mode=suspend</code>. In the event that an administrator specifies a suspended start as well as a
non-graceful start, the suspended start will "win". That is to say, the server will start in a suspended mode,
the <code>graceful-start=false</code> will be disregarded, and the server will log a message indicating that this is happening.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Starting_and_Stopping_Servers_in_a_Managed_Domain"><a class="anchor" href="#Starting_and_Stopping_Servers_in_a_Managed_Domain"></a><a class="link" href="#Starting_and_Stopping_Servers_in_a_Managed_Domain">9.3. Starting and Stopping Servers in a Managed Domain</a></h3>
<div class="paragraph">
<p>Starting a standalone server is done through the <code>bin/standalone.sh</code>
script. However in a managed domain server instances are managed by the
domain controller and need to be started through the management layer:</p>
</div>
<div class="paragraph">
<p>First of all, get to know which <code>servers</code> are configured on a particular
<code>host</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] :read-children-names(child-type=host)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [&quot;local&quot;]
}
 
 
[domain@localhost:9990 /] /host=local:read-children-names(child-type=server-config)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; [
       &quot;my-server&quot;,
       &quot;server-one&quot;,
       &quot;server-three&quot;
   ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now that we know, that there are two <code>servers</code> configured on <code>host</code> "
<em>local</em>", we can go ahead and check their status:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=local/server-config=server-one:read-resource(include-runtime=true)
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; {
       &quot;auto-start&quot; =&gt; true,
       &quot;group&quot; =&gt; &quot;main-server-group&quot;,
       &quot;interface&quot; =&gt; undefined,
       &quot;name&quot; =&gt; &quot;server-one&quot;,
       &quot;path&quot; =&gt; undefined,
       &quot;socket-binding-group&quot; =&gt; undefined,
       &quot;socket-binding-port-offset&quot; =&gt; undefined,
       &quot;status&quot; =&gt; &quot;STARTED&quot;,
       &quot;system-property&quot; =&gt; undefined,
       &quot;jvm&quot; =&gt; {&quot;default&quot; =&gt; undefined}
   }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can change the server state through the " <em>start</em>" and " <em>stop</em>"
operations</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=local/server-config=server-one:stop
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; &quot;STOPPING&quot;
}</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Navigating through the domain topology is much more simple when you use
the web interface.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="JVM_settings"><a class="anchor" href="#JVM_settings"></a><a class="link" href="#JVM_settings">9.4. JVM settings</a></h3>
<div class="paragraph">
<p>Configuration of the JVM settings is different for a managed domain and
a standalone server. In a managed domain, the domain controller
components are responsible for starting and stopping server processes and
hence determine the JVM settings. For a standalone server, it&#8217;s the
responsibility of the process that started the server (e.g. passing them
as command line arguments).</p>
</div>
<div class="sect3">
<h4 id="managed-domain-5"><a class="anchor" href="#managed-domain-5"></a><a class="link" href="#managed-domain-5">9.4.1. Managed Domain</a></h4>
<div class="paragraph">
<p>In a managed domain the JVM settings can be declared at different
scopes: For a specific server group, for a host or for a particular
server. If not declared, the settings are inherited from the parent
scope. This allows you to customize or extend the JVM settings within
every layer.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s take a look at the JVM declaration for a server group:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;server-groups&gt;</span>
       <span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
               <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">512m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
           <span class="tag">&lt;/jvm&gt;</span>
           <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/server-group&gt;</span>
       <span class="tag">&lt;server-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">profile</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
               <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">512m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
           <span class="tag">&lt;/jvm&gt;</span>
           <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/server-group&gt;</span>
<span class="tag">&lt;/server-groups&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p><sub>(See</sub> <code>domain/configuration/domain.xml</code> <sub>)</sub></p>
</div>
<div class="paragraph">
<p>In this example the server group "main-server-group" declares a heap
size of <code>64m</code> and a maximum heap size of <code>512m</code>. Any server that belongs
to this group will inherit these settings. You can change these settings
for the group as a whole, or a specific server or host:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;servers&gt;</span>
       <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-one</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-start</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/server&gt;</span>
       <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-two</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">main-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-start</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;jvm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
               <span class="tag">&lt;heap</span> <span class="attribute-name">size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">64m</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">max-size</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">256m</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
           <span class="tag">&lt;/jvm&gt;</span>
           <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port-offset</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">150</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/server&gt;</span>
       <span class="tag">&lt;server</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">server-three</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other-server-group</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">auto-start</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
           <span class="tag">&lt;socket-binding-group</span> <span class="attribute-name">ref</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">standard-sockets</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port-offset</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">250</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
       <span class="tag">&lt;/server&gt;</span>
<span class="tag">&lt;/servers&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>In this case, <em>server-two</em>, belongs to the <em>main-server-group</em> and
inherits the JVM settings named <em>default</em>, but declares a lower maximum
heap size.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9999 /] /host=local/server-config=server-two/jvm=default:read-resource
{
   &quot;outcome&quot; =&gt; &quot;success&quot;,
   &quot;result&quot; =&gt; {
       &quot;heap-size&quot; =&gt; &quot;64m&quot;,
       &quot;max-heap-size&quot; =&gt; &quot;256m&quot;,
   }
}</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="using-filesystem-locations-as-jvm-options-on-domain-mode"><a class="anchor" href="#using-filesystem-locations-as-jvm-options-on-domain-mode"></a><a class="link" href="#using-filesystem-locations-as-jvm-options-on-domain-mode">Using filesystem locations as JVM options on domain mode</a></h5>
<div class="paragraph">
<p>The <a href="Admin_Guide.html#controlling-filesystem-locations-with-system-properties">Controlling filesystem locations with system properties</a> section describes the available system properties associated with relevant WildFly file system paths. In addition to all the domain mode properties, the following server specific properties are also available for resolution as JVM options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>jboss.server.base.dir</p>
</li>
<li>
<p>jboss.server.log.dir</p>
</li>
<li>
<p>jboss.server.data.dir</p>
</li>
<li>
<p>jboss.server.temp.dir</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This ability is useful when you need to configure JVM settings without specifying a specific server name. For example, if you want to redirect the GC logging to a file to the default log server directory, you can configure the following JVM option at host level:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=primary/jvm=default:add-jvm-option(jvm-option=&quot;-Xlog:gc:file=${jboss.server.log.dir}/gc.log&quot;)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {&quot;main-server-group&quot; =&gt; {&quot;host&quot; =&gt; {&quot;primary&quot; =&gt; {&quot;server-two&quot; =&gt; {&quot;response&quot; =&gt; {
        &quot;outcome&quot; =&gt; &quot;success&quot;,
        &quot;response-headers&quot; =&gt; {
            &quot;operation-requires-restart&quot; =&gt; true,
            &quot;process-state&quot; =&gt; &quot;restart-required&quot;
        }
    }}}}}}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="standalone-server-4"><a class="anchor" href="#standalone-server-4"></a><a class="link" href="#standalone-server-4">9.4.2. Standalone Server</a></h4>
<div class="paragraph">
<p>For a standalone sever you have to pass in the JVM settings either as
command line arguments when executing the
<code>$JBOSS_HOME/bin/standalone.sh</code> script, or by declaring them in
<code>$JBOSS_HOME/bin/standalone.conf</code>. (For Windows users, the script to
execute is <code>%JBOSS_HOME%/bin/standalone.bat</code> while the JVM settings can
be declared in <code>%JBOSS_HOME%/bin/standalone.conf.bat.)</code></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Audit_logging"><a class="anchor" href="#Audit_logging"></a><a class="link" href="#Audit_logging">9.5. Audit logging</a></h3>
<div class="paragraph">
<p>WildFly comes with audit logging built in for management operations
affecting the management model. By default it is turned off. The
information is output as JSON records.</p>
</div>
<div class="paragraph">
<p>The default configuration of audit logging in standalone.xml looks as
follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">    <span class="tag">&lt;management&gt;</span>
        <span class="tag">&lt;audit-log&gt;</span>
            <span class="tag">&lt;formatters&gt;</span>
                <span class="tag">&lt;json-formatter</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">json-formatter</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;/formatters&gt;</span>
            <span class="tag">&lt;handlers&gt;</span>
                <span class="tag">&lt;file-handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">file</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">formatter</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">json-formatter</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">path</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">audit-log.log</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">relative-to</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">jboss.server.data.dir</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
            <span class="tag">&lt;/handlers&gt;</span>
            <span class="tag">&lt;logger</span> <span class="attribute-name">log-boot</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">log-read-only</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">enabled</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">false</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;handlers&gt;</span>
                    <span class="tag">&lt;handler</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">file</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
                <span class="tag">&lt;/handlers&gt;</span>
            <span class="tag">&lt;/logger&gt;</span>
        <span class="tag">&lt;/audit-log&gt;</span>
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Looking at this via the CLI it looks like</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/access=audit:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;file-handler&quot; =&gt; {&quot;file&quot; =&gt; {
            &quot;formatter&quot; =&gt; &quot;json-formatter&quot;,
            &quot;max-failure-count&quot; =&gt; 10,
            &quot;path&quot; =&gt; &quot;audit-log.log&quot;,
            &quot;relative-to&quot; =&gt; &quot;jboss.server.data.dir&quot;
        }},
        &quot;json-formatter&quot; =&gt; {&quot;json-formatter&quot; =&gt; {
            &quot;compact&quot; =&gt; false,
            &quot;date-format&quot; =&gt; &quot;yyyy-MM-dd HH:mm:ss&quot;,
            &quot;date-separator&quot; =&gt; &quot; - &quot;,
            &quot;escape-control-characters&quot; =&gt; false,
            &quot;escape-new-line&quot; =&gt; false,
            &quot;include-date&quot; =&gt; true
        }},
        &quot;logger&quot; =&gt; {&quot;audit-log&quot; =&gt; {
            &quot;enabled&quot; =&gt; false,
            &quot;log-boot&quot; =&gt; true,
            &quot;log-read-only&quot; =&gt; false,
            &quot;handler&quot; =&gt; {&quot;file&quot; =&gt; {}}
        }},
        &quot;syslog-handler&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To enable it via CLI you need just</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Audit data are stored in standalone/data/audit-log.log.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The audit logging subsystem has a lot of internal dependencies, and it
logs operations changing, enabling and disabling its components. When
configuring or changing things at runtime it is a good idea to make
these changes as part of a CLI batch. For example if you are adding a
syslog handler you need to add the handler and its information as one
step. Similarly if you are using a file handler, and want to change its
<code>path</code> and <code>relative-to</code> attributes, that needs to happen as one step.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="audit-logging-json-formatter"><a class="anchor" href="#audit-logging-json-formatter"></a><a class="link" href="#audit-logging-json-formatter">9.5.1. JSON Formatter</a></h4>
<div class="paragraph">
<p>The first thing that needs configuring is the formatter, we currently
support outputting log records as JSON. You can define several
formatters, for use with different handlers. A log record has the
following format, and it is the formatter&#8217;s job to format the data
presented:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>2013-08-12 11:01:12 - {
    &quot;type&quot; : &quot;core&quot;,
    &quot;r/o&quot; : false,
    &quot;booting&quot; : false,
    &quot;version&quot; : &quot;8.0.0.Alpha4&quot;,
    &quot;user&quot; : &quot;$local&quot;,
    &quot;domainUUID&quot; : null,
    &quot;access&quot; : &quot;NATIVE&quot;,
    &quot;remote-address&quot; : &quot;127.0.0.1/127.0.0.1&quot;,
    &quot;success&quot; : true,
    &quot;ops&quot; : [JMX|WFLY8:JMX subsystem configuration],
        &quot;operation&quot; : &quot;write-attribute&quot;,
        &quot;name&quot; : &quot;enabled&quot;,
        &quot;value&quot; : true,
        &quot;operation-headers&quot; : {&quot;caller-type&quot; : &quot;user&quot;}
    }]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>It includes an optional timestamp and then the following information in
the json record</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This can have the values core, meaning it is a management
operation, or jmx meaning it comes from the jmx subsystem (see the jmx
subsystem for configuration of the jmx subsystem&#8217;s audit logging)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">r/o</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if the operation does not change the management model, false
otherwise</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">booting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if the operation was executed during the bootup process,
false if it was executed once the server is up and running</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">version</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The version number of the WildFly instance</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">user</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The username of the authenticated user. In this case the
operation has been logged via the CLI on the same machine as the running
server, so the special $local user is used</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">domainUUID</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">An ID to link together all operations as they are
propagated from the Domain Controller to its servers, secondary Host
Controllers, and secondary Host Controller servers</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">access</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This can have one of the following values:*NATIVE - The
operation came in through the native management interface, for example
the CLI*HTTP - The operation came in through the domain HTTP interface,
for example the admin console*JMX - The operation came in through the
JMX subsystem. See JMX for how to configure audit logging for JMX.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">remote-address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The address of the client executing this operation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">success</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if the operation succeeded, false if it was rolled back</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ops</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The operations being executed. This is a list of the operations
serialized to JSON. At boot this will be all the operations resulting
from parsing the xml. Once booted the list will typically just contain a
single entry</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The json formatter resource has the following attributes:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">include-date</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolan toggling whether or not to include the timestamp
in the formatted log records</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">date-separator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A string containing characters to separate the date and
the rest of the formatted log message. Will be ignored if
include-date=false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">date-format</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The date format to use for the timestamp as understood by
java.text.SimpleDateFormat. Will be ignored if include-date=false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compact</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true will format the JSON on one line. There may still be
values containing new lines, so if having the whole record on one line
is important, set escape-new-line or escape-control-characters to true</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">escape-control-characters</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true it will escape all control
characters (ascii entries with a decimal value &lt; 32) with the ascii code
in octal, e.g. a new line becomes '#012'. If this is true, it will
override escape-new-line=false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">escape-new-line</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true it will escape all new lines with the ascii
code in octal, e.g. "#012".</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="handlers-3"><a class="anchor" href="#handlers-3"></a><a class="link" href="#handlers-3">9.5.2. Handlers</a></h4>
<div class="paragraph">
<p>A handler is responsible for taking the formatted data and logging it to
a location. There are currently two types of handlers, File and Syslog.
You can configure several of each type of handler and use them to log
information.</p>
</div>
<div class="sect4">
<h5 id="file-handler-2"><a class="anchor" href="#file-handler-2"></a><a class="link" href="#file-handler-2">File handler</a></h5>
<div class="paragraph">
<p>The file handlers log the audit log records to a file on the server. The
attributes for the file handler are</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Read Only</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">formatter</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of a JSON formatter to use to format the log
records</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The path of the audit log file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">relative-to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of another previously named path, or of one of
the standard paths provided by the system. If relative-to is provided,
the value of the path attribute is treated as relative to the path
specified by this attribute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">failure-count</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The number of logging failures since the handler was
initialized</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-failure-count</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of logging failures before
disabling this handler</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">disabled-due-to-failure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if this handler was disabled due to
logging failures</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In our standard configuration <code>path=audit-log.log</code> and
<code>relative-to=jboss.server.data.dir</code>, typically this will be
<code>$JBOSS_HOME/standalone/data/audit-log.log</code></p>
</div>
</div>
<div class="sect4">
<h5 id="audit-syslog-handler"><a class="anchor" href="#audit-syslog-handler"></a><a class="link" href="#audit-syslog-handler">Syslog handler</a></h5>
<div class="paragraph">
<p>The default configuration does not have syslog audit logging set up.
Syslog is a better choice for audit logging since you can log to a
remote syslog server, and secure the authentication to happen over TLS
with client certificate authentication. Syslog servers vary a lot in
their capabilities so not all settings in this section apply to all
syslog servers. We have tested with <a href="http://www.rsyslog.com">rsyslog</a>.</p>
</div>
<div class="paragraph">
<p>The address for the syslog handler is
<code>/core-service=management/access=audit/syslog-handler=*</code> and just like
file handlers you can add as many syslog entries as you like. The syslog
handler resources reference the main RFC&#8217;s for syslog a fair bit, for
reference they can be found at:<br>
* <a href="http://www.ietf.org/rfc/rfc3164.txt" class="bare">http://www.ietf.org/rfc/rfc3164.txt</a><br>
* <a href="http://www.ietf.org/rfc/rfc5424.txt" class="bare">http://www.ietf.org/rfc/rfc5424.txt</a><br>
* <a href="http://www.ietf.org/rfc/rfc6587.txt" class="bare">http://www.ietf.org/rfc/rfc6587.txt</a></p>
</div>
<div class="paragraph">
<p>The syslog handler resource has the following attributes:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">formatter</th>
<th class="tableblock halign-left valign-top">The name of a JSON formatter to use to format the log
records</th>
<th class="tableblock halign-left valign-top">false</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">failure-count</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The number of logging failures since the handler was
initialized</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-failure-count</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of logging failures before
disabling this handler</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">disabled-due-to-failure</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true if this handler was disabled due to
logging failures</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">syslog-format</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Whether to set the syslog format to the one specified in
RFC-5424 or RFC-3164</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-length</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum length in bytes a log message, including the
header, is allowed to be. If undefined, it will default to 1024 bytes if
the syslog-format is RFC3164, or 2048 bytes if the syslog-format is
RFC5424.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">truncate</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Whether or not a message, including the header, should
truncate the message if the length in bytes is greater than the maximum
length. If set to false messages will be split and sent with the same
header values</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>When adding a syslog handler you also need to add the protocol it will
use to communicate with the syslog server. The valid choices for
protocol are <code>UDP</code>, <code>TCP</code> and <code>TLS</code>. The protocol must be added at the
same time as you add the syslog handler, or it will fail. Also, you can
only add one protocol for the handler.</p>
</div>
<div class="sect5">
<h6 id="udp"><a class="anchor" href="#udp"></a><a class="link" href="#udp">UDP</a></h6>
<div class="paragraph">
<p>Configures the handler to use UDP to communicate with the syslog server.
The address of the <code>UDP</code> resource is
<code>/core-service=management/access=audit/syslog-handler=*/protocol=udp</code>.
The attributes of the <code>UDP</code> resource are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The host of the syslog server for the udp requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The port of the syslog server listening for the udp requests</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="tcp"><a class="anchor" href="#tcp"></a><a class="link" href="#tcp">TCP</a></h6>
<div class="paragraph">
<p>Configures the handler to use TCP to communicate with the syslog server.
The address of the <code>TCP</code> resource is
<code>/core-service=management/access=audit/syslog-handler=*/protocol=tcp</code>.
The attributes of the <code>TCP</code> resource are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The host of the syslog server for the tcp requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The port of the syslog server listening for the tcp requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">message-transfer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The message transfer setting as described in section
3.4 of RFC-6587. This can either be OCTET_COUNTING as described in
section 3.4.1 of RFC-6587, or NON_TRANSPARENT_FRAMING as described in
section 3.4.1 of RFC-6587</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="tls"><a class="anchor" href="#tls"></a><a class="link" href="#tls">TLS</a></h6>
<div class="paragraph">
<p>Configures the handler to use TLC to communicate securely with the
syslog server. The address of the <code>TLS</code> resource is
<code>/core-service=management/access=audit/syslog-handler=*/protocol=tls</code>.
The attributes of the <code>TLS</code> resource are the same as for <code>TCP</code>:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The host of the syslog server for the tls requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The port of the syslog server listening for the tls requests</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">message-transfer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The message transfer setting as described in section
3.4 of RFC-6587. This can either be OCTET_COUNTING as described in
section 3.4.1 of RFC-6587, or NON_TRANSPARENT_FRAMING as described in
section 3.4.1 of RFC-6587</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>If the syslog server&#8217;s TLS certificate is not signed by a certificate
signing authority, you will need to set up a truststore to trust the
certificate. The resource for the trust store is a child of the <code>TLS</code>
resource, and the full address is
<code>/core-service=management/access=audit/syslog-handler=*/protocol=tls/authentication=truststore</code>.
The attributes of the truststore resource are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-password</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The password for the truststore</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The path of the truststore</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-relative-to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of another previously named path, or of
one of the standard paths provided by the system. If
keystore-relative-to is provided, the value of the keystore-path
attribute is treated as relative to the path specified by this attribute</p></td>
</tr>
</tbody>
</table>
<div class="sect6">
<h7 id="tls-with-client-certificate-authentication."><a class="anchor" href="#tls-with-client-certificate-authentication."></a><a class="link" href="#tls-with-client-certificate-authentication.">TLS with Client certificate authentication.</a></h7>
<div class="paragraph">
<p>If you have set up the syslog server to require client certificate
authentication, when creating your handler you will also need to set up
a client certificate store containing the certificate to be presented to
the syslog server. The address of the client certificate store resource
is
<code>/core-service=management/access=audit/syslog-handler=*/protocol=tls/authentication=client-certificate-store</code>
and its attributes are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-password</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The password for the keystore</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">key-password</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The password for the keystore key</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The path of the keystore</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keystore-relative-to</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of another previously named path, or of
one of the standard paths provided by the system. If
keystore-relative-to is provided, the value of the keystore-path
attribute is treated as relative to the path specified by this attribute</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="logger-configuration"><a class="anchor" href="#logger-configuration"></a><a class="link" href="#logger-configuration">9.5.3. Logger configuration</a></h4>
<div class="paragraph">
<p>The final part that needs configuring is the logger for the management
operations. This references one or more handlers and is configured at
<code>/core-service=management/access=audit/logger=audit-log</code>. The attributes
for this resource are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enabled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true to enable logging of the management operations</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">log-boot</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true to log the management operations when booting the
server, false otherwise</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">log-read-only</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true all operations will be audit logged, if false
only operations that change the model will be logged</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Then which handlers are used to log the management operations are
configured as <code>handler=*</code> children of the logger.</p>
</div>
</div>
<div class="sect3">
<h4 id="domain-mode-host-specific-configuration"><a class="anchor" href="#domain-mode-host-specific-configuration"></a><a class="link" href="#domain-mode-host-specific-configuration">9.5.4. Domain Mode (host specific configuration)</a></h4>
<div class="paragraph">
<p>In domain mode audit logging is configured for each host in its
<code>host.xml</code> file. This means that when connecting to the DC, the
configuration of the audit logging is under the host&#8217;s entry, e.g. here
is the default configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=primary/core-service=management/access=audit:read-resource(recursive=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;file-handler&quot; =&gt; {
            &quot;host-file&quot; =&gt; {
                &quot;formatter&quot; =&gt; &quot;json-formatter&quot;,
                &quot;max-failure-count&quot; =&gt; 10,
                &quot;path&quot; =&gt; &quot;audit-log.log&quot;,
                &quot;relative-to&quot; =&gt; &quot;jboss.domain.data.dir&quot;
            },
            &quot;server-file&quot; =&gt; {
                &quot;formatter&quot; =&gt; &quot;json-formatter&quot;,
                &quot;max-failure-count&quot; =&gt; 10,
                &quot;path&quot; =&gt; &quot;audit-log.log&quot;,
                &quot;relative-to&quot; =&gt; &quot;jboss.server.data.dir&quot;
            }
        },
        &quot;json-formatter&quot; =&gt; {&quot;json-formatter&quot; =&gt; {
            &quot;compact&quot; =&gt; false,
            &quot;date-format&quot; =&gt; &quot;yyyy-MM-dd HH:mm:ss&quot;,
            &quot;date-separator&quot; =&gt; &quot; - &quot;,
            &quot;escape-control-characters&quot; =&gt; false,
            &quot;escape-new-line&quot; =&gt; false,
            &quot;include-date&quot; =&gt; true
        }},
        &quot;logger&quot; =&gt; {&quot;audit-log&quot; =&gt; {
            &quot;enabled&quot; =&gt; false,
            &quot;log-boot&quot; =&gt; true,
            &quot;log-read-only&quot; =&gt; false,
            &quot;handler&quot; =&gt; {&quot;host-file&quot; =&gt; {}}
        }},
        &quot;server-logger&quot; =&gt; {&quot;audit-log&quot; =&gt; {
            &quot;enabled&quot; =&gt; false,
            &quot;log-boot&quot; =&gt; true,
            &quot;log-read-only&quot; =&gt; false,
            &quot;handler&quot; =&gt; {&quot;server-file&quot; =&gt; {}}
        }},
        &quot;syslog-handler&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>We now have two file handlers, one called <code>host-file</code> used to configure
the file to log management operations on the host, and one called
<code>server-file</code> used to log management operations executed on the servers.
Then <code>logger=audit-log</code> is used to configure the logger for the host
controller, referencing the <code>host-file</code> handler.
<code>server-logger=audit-log</code> is used to configure the logger for the
managed servers, referencing the <code>server-file</code> handler. The attributes
for <code>server-logger=audit-log</code> are the same as for
<code>server-logger=audit-log</code> in the previous section. Having the host
controller and server loggers configured independently means we can
control audit logging for managed servers and the host controller
independently.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Canceling_Management_Operations"><a class="anchor" href="#Canceling_Management_Operations"></a><a class="link" href="#Canceling_Management_Operations">9.6. Canceling Management Operations</a></h3>
<div class="paragraph">
<p>WildFly includes the ability to use the CLI to cancel management
requests that are not proceeding normally.</p>
</div>
<div class="sect3">
<h4 id="the-cancel-non-progressing-operation-operation"><a class="anchor" href="#the-cancel-non-progressing-operation-operation"></a><a class="link" href="#the-cancel-non-progressing-operation-operation">9.6.1. The cancel-non-progressing-operation operation</a></h4>
<div class="paragraph">
<p>The <code>cancel-non-progressing-operation</code> operation instructs the target
process to find any operation that isn&#8217;t proceeding normally and cancel
it.</p>
</div>
<div class="paragraph">
<p>On a standalone server:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations:cancel-non-progressing-operation
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;-1155777943&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The result value is an internal identification number for the operation
that was cancelled.</p>
</div>
<div class="paragraph">
<p>On a managed domain host controller, the equivalent resource is in the
host=&lt;hostname&gt; portion of the management resource tree:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=host-a/core-service=management/service=management-operations:cancel-non-progressing-operation
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;2156877946&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An operation can be cancelled on an individual managed domain server as
well:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=host-a/server=server-one/core-service=management/service=management-operations:cancel-non-progressing-operation
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;6497786512&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An operation is considered to be not proceeding normally if it has been
executing with the exclusive operation lock held for longer than 15
seconds. Read-only operations do not acquire the exclusive operation
lock, so this operation will not cancel read-only operations. Operations
blocking waiting for another operation to release the exclusive lock
will also not be cancelled.</p>
</div>
<div class="paragraph">
<p>If there isn&#8217;t any operation that is failing to proceed normally, there
will be a failure response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations:cancel-non-progressing-operation
{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;WFLYDM0089: No operation was found that has been holding the operation execution write lock for long than [15] seconds&quot;,
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="the-find-non-progressing-operation-operation"><a class="anchor" href="#the-find-non-progressing-operation-operation"></a><a class="link" href="#the-find-non-progressing-operation-operation">9.6.2. The find-non-progressing-operation operation</a></h4>
<div class="paragraph">
<p>To simply learn the id of an operation that isn&#8217;t proceeding normally,
but not cancel it, use the <code>find-non-progressing-operation</code> operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations:find-non-progressing-operation
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;-1155777943&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If there is no non-progressing operation, the outcome will still be
<code>success</code> but the result will be <code>undefined</code>.</p>
</div>
<div class="paragraph">
<p>Once the id of the operation is known, the management resource for the
operation can be examined to learn more about its status.</p>
</div>
</div>
<div class="sect3">
<h4 id="examining-the-status-of-an-active-operation"><a class="anchor" href="#examining-the-status-of-an-active-operation"></a><a class="link" href="#examining-the-status-of-an-active-operation">9.6.3. Examining the status of an active operation</a></h4>
<div class="paragraph">
<p>There is a management resource for any currently executing operation
that can be queried:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations/active-operation=-1155777943:read-resource(include-runtime=true)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;access-mechanism&quot; =&gt; &quot;undefined&quot;,
        &quot;address&quot; =&gt; [
            (&quot;deployment&quot; =&gt; &quot;example&quot;)
        ],
        &quot;caller-thread&quot; =&gt; &quot;management-handler-thread - 24&quot;,
        &quot;cancelled&quot; =&gt; false,
        &quot;exclusive-running-time&quot; =&gt; 101918273645L,
        &quot;execution-status&quot; =&gt; &quot;awaiting-stability&quot;,
        &quot;operation&quot; =&gt; &quot;deploy&quot;,
        &quot;running-time&quot; =&gt; 101918279999L
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The response includes the following attributes:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">access-mechanism</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The mechanism used to submit a request to the server.
NATIVE, JMX, HTTP</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The address of the resource targeted by the operation. The
value in the final element of the address will be '&lt;hidden&gt;' if the
caller is not authorized to address the operation&#8217;s target resource.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">caller-thread</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the thread that is executing the operation.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">cancelled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Whether the operation has been cancelled.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>exclusive-status</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Amount of time in nanoseconds the operation has
been executing with the exclusive operation execution lock held, or -1
if the operation does not hold the exclusive execution lock.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">execution-status</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The current activity of the operation. See below for
details.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">operation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the operation, or '&lt;hidden&gt;' if the caller is
not authorized to address the operation&#8217;s target resource.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">running-time</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Amount of time the operation has been executing, in
nanoseconds.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The following are the values for the <code>exclusive-running-time</code> attribute:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Value</th>
<th class="tableblock halign-left valign-top">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">executing</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The caller thread is actively executing</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">awaiting-other-operation</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The caller thread is blocking waiting for
another operation to release the exclusive execution lock</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">awaiting-stability</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The caller thread has made changes to the service
container and is waiting for the service container to stabilize</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">completing</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The operation is committed and is completing execution</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">rolling-back</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The operation is rolling back</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>All currently executing operations can be viewed in one request using
the <code>read-children-resources</code> operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations:read-children-resources(child-type=active-operation)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;-1155777943&quot; =&gt; {
        &quot;access-mechanism&quot; =&gt; &quot;undefined&quot;,
        &quot;address&quot; =&gt; [
            (&quot;deployment&quot; =&gt; &quot;example&quot;)
        ],
        &quot;caller-thread&quot; =&gt; &quot;management-handler-thread - 24&quot;,
        &quot;cancelled&quot; =&gt; false,
        &quot;exclusive-running-time&quot; =&gt; 101918273645L,
        &quot;execution-status&quot; =&gt; &quot;awaiting-stability&quot;,
        &quot;operation&quot; =&gt; &quot;deploy&quot;,
        &quot;running-time&quot; =&gt; 101918279999L
    },
    {&quot;-1246693202&quot; =&gt; {
        &quot;access-mechanism&quot; =&gt; &quot;undefined&quot;,
        &quot;address&quot; =&gt; [
            (&quot;core-service&quot; =&gt; &quot;management&quot;),
            (&quot;service&quot; =&gt; &quot;management-operations&quot;)
        ],
        &quot;caller-thread&quot; =&gt; &quot;management-handler-thread - 30&quot;,
        &quot;cancelled&quot; =&gt; false,
        &quot;exclusive-running-time&quot; =&gt; -1L,
        &quot;execution-status&quot; =&gt; &quot;executing&quot;,
        &quot;operation&quot; =&gt; &quot;read-children-resources&quot;,
        &quot;running-time&quot; =&gt; 3356000L
    }}
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="canceling-a-specific-operation"><a class="anchor" href="#canceling-a-specific-operation"></a><a class="link" href="#canceling-a-specific-operation">9.6.4. Canceling a specific operation</a></h4>
<div class="paragraph">
<p>The <code>cancel-non-progressing-operation</code> operation is a convenience
operation for identifying and canceling an operation. However, an
administrator can examine the active-operation resources to identify any
operation, and then directly cancel it by invoking the <code>cancel</code>
operation on the resource for the desired operation.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /core-service=management/service=management-operations/active-operation=-1155777943:cancel
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="controlling-operation-blocking-time"><a class="anchor" href="#controlling-operation-blocking-time"></a><a class="link" href="#controlling-operation-blocking-time">9.6.5. Controlling operation blocking time</a></h4>
<div class="paragraph">
<p>As an operation executes, the execution thread may block at various
points, particularly while waiting for the service container to
stabilize following any changes. Since an operation may be holding the
exclusive execution lock while blocking, in WildFly execution behavior
was changed to ensure that blocking will eventually time out, resulting
in roll back of the operation.</p>
</div>
<div class="paragraph">
<p>The default blocking timeout is 300 seconds. This is intentionally long,
as the idea is to only trigger a timeout when something has definitely
gone wrong with the operation, without any false positives.</p>
</div>
<div class="paragraph">
<p>An administrator can control the blocking timeout for an individual
operation by using the <code>blocking-timeout</code> operation header. For example,
if a particular deployment is known to take an extremely long time to
deploy, the default 300 second timeout could be increased:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] deploy /tmp/mega.war --headers={blocking-timeout=450}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the blocking timeout is <strong>not</strong> a guaranteed maximum execution time
for an operation. If it only a timeout that will be enforced at various
points during operation execution.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Configuration_file_history"><a class="anchor" href="#Configuration_file_history"></a><a class="link" href="#Configuration_file_history">9.7. Configuration file history</a></h3>
<div class="paragraph">
<p>The management operations may modify the model. When this occurs the xml
backing the model is written out again reflecting the latest changes. In
addition a full history of the file is maintained. The history of the
file goes in a separate directory under the configuration directory.</p>
</div>
<div class="paragraph">
<p>As mentioned in <a href="#Command_line_parameters">Command line parameters</a> the default
configuration file can be selected using a command-line parameter. For a
standalone server instance the history of the active <code>standalone.xml</code> is
kept in <code>jboss.server.config.dir</code>/standalone_xml_history (See
<a href="#Command_line_parameters">Command line parameters#standalone_system_properties</a>
for more details). For a domain the active <code>domain.xml</code> and <code>host.xml</code>
histories are kept in <code>jboss.domain.config.dir</code>/domain_xml_history and
<code>jboss.domain.config.dir</code>/host_xml_history.</p>
</div>
<div class="paragraph">
<p>The rest of this section will only discuss the history for
<code>standalone.xml</code>. The concepts are exactly the same for <code>domain.xml</code> and
<code>host.xml</code>.</p>
</div>
<div class="paragraph">
<p>Within <code>standalone_xml_history</code> itself following a successful first time
boot we end up with three new files:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>standalone.initial.xml</code> - This contains the original configuration
that was used the first time we successfully booted. This file will
never be overwritten. You may of course delete the history directory and
any files in it at any stage.</p>
</li>
<li>
<p><code>standalone.boot.xml</code> - This contains the original configuration that
was used for the last successful boot of the server. This gets
overwritten every time we boot the server successfully.</p>
</li>
<li>
<p><code>standalone.last.xml</code> - At this stage the contents will be identical
to <code>standalone.boot.xml</code>. This file gets overwritten each time the
server successfully writes the configuration, if there was an unexpected
failure writing the configuration this file is the last known successful
write.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><code>standalone_xml_history</code> contains a directory called <code>current</code> which
should be empty. Now if we execute a management operation that modifies
the model, for example adding a new system property using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /system-property=test:add(value=&quot;test123&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>What happens is:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The original configuration file is backed up to
<code>standalone_xml_history/current/standalone.v1.xml</code>. The next change to
the model would result in a file called <code>standalone.v2.xml</code> etc. The 100
most recent of these files are kept.</p>
</li>
<li>
<p>The change is applied to the original configuration file</p>
</li>
<li>
<p>The changed original configuration file is copied to
<code>standalone.last.xml</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When restarting the server, any existing
<code>standalone_xml_history/current</code> directory is moved to a new timestamped
folder within the <code>standalone_xml_history</code>, and a new <code>current</code> folder
is created. These timestamped folders are kept for 30 days.</p>
</div>
<div class="sect3">
<h4 id="snapshots-file-history"><a class="anchor" href="#snapshots-file-history"></a><a class="link" href="#snapshots-file-history">9.7.1. Snapshots</a></h4>
<div class="paragraph">
<p>In addition to the backups taken by the server as described above you
can manually take snapshots which will be stored in the <code>snapshot</code>
folder under the <code>_xml_history</code> folder, the automatic backups described
above are subject to automatic house keeping so will eventually be
automatically removed, the snapshots on the other hand can be entirely
managed by the administrator.</p>
</div>
<div class="paragraph">
<p>You may also take your own snapshots using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :take-snapshot
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;name&quot; =&gt; &quot;/Users/kabir/wildfly/standalone/configuration/standalone_xml_history/snapshot/20110630-172258657standalone.xml&quot;}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also use the CLI to list all the snapshots</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :list-snapshots
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;directory&quot; =&gt; &quot;/Users/kabir/wildfly/standalone/configuration/standalone_xml_history/snapshot&quot;,
        &quot;names&quot; =&gt; [
            &quot;20110630-165714239standalone.xml&quot;,
            &quot;20110630-165821795standalone.xml&quot;,
            &quot;20110630-170113581standalone.xml&quot;,
            &quot;20110630-171411463standalone.xml&quot;,
            &quot;20110630-171908397standalone.xml&quot;,
            &quot;20110630-172258657standalone.xml&quot;
        ]
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To delete a particular snapshot:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :delete-snapshot(name=&quot;20110630-165714239standalone.xml&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>and to delete all snapshots:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :delete-snapshot(name=&quot;all&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In domain mode executing the snapshot operations against the root node
will work against the domain model. To do this for a host model you need
to navigate to the host in question:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=primary:list-snapshots
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;domain-results&quot; =&gt; {&quot;step-1&quot; =&gt; {
            &quot;directory&quot; =&gt; &quot;/Users/kabir/wildfly/domain/configuration/host_xml_history/snapshot&quot;,
            &quot;names&quot; =&gt; [
                &quot;20110630-141129571host.xml&quot;,
                &quot;20110630-172522225host.xml&quot;
            ]
        }},
        &quot;server-operations&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="subsequent-starts"><a class="anchor" href="#subsequent-starts"></a><a class="link" href="#subsequent-starts">9.7.2. Subsequent Starts</a></h4>
<div class="paragraph">
<p>For subsequent server starts it may be desirable to take the state of
the server back to one of the previously known states, for a number of
items an abbreviated reverence to the file can be used:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbreviation</th>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">initial</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config=initial</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This will start the server using the
initial configuration first used to start the server.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">boot</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config=boot</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This will use the configuration from the
last successful boot of the server.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">last</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config=last</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This will start the server using the
configuration backed up from the last successful save.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">v?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config=v?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This will server the _xml_history/current
folder for the configuration where ? is the number of the backup to use.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">-?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">--server-config=-?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The server will be started after searching the
snapshot folder for the configuration which matches this prefix.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In addition to this the <code>--server-config</code> parameter can always be used
to specify a configuration relative to the <code>jboss.server.config.dir</code> and
finally if no matching configuration is found an attempt to locate the
configuration as an absolute path will be made.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Configuration_file_git_history"><a class="anchor" href="#Configuration_file_git_history"></a><a class="link" href="#Configuration_file_git_history">9.8. Git Configuration file history</a></h3>
<div class="paragraph">
<p>To enhance the initial <a href="#Configuration_file_history">configuration file history</a> we have now a native Git support to manage the configuration history. This feature goes a little farther than the initial configuration file history in that it also manages content repository content and all the configuration files (such as properties). This feature only work for <strong>standalone servers</strong> using the default directory layout.</p>
</div>
<div class="paragraph">
<p>As mentioned in <a href="#Command_line_parameters">Command line parameters</a> we support the usage of a remote Git repository to pull the configuration from or create or use a local Git repository.
In fact if a <code>.git</code> directory exists under <code>jboss.server.base.dir</code> then using Git for managing configuration files will be automatically activated.
Each modification of the content or the configuration will result in a new commit when the operation is successful and there are changes to commit. If there is an authenticated user then it will be stored as the author of the commit.
Please note that this is a real Git repository so using a native Git client you can manipulate it.</p>
</div>
<div class="paragraph">
<p>Now if we execute a management operation that modifies
the model, for example adding a new system property using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /system-property=test:add(value=&quot;test123&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>What happens is:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The change is applied to the configuration file.</p>
</li>
<li>
<p>The configuration file is added to a new commit.</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="local_git_repository"><a class="anchor" href="#local_git_repository"></a><a class="link" href="#local_git_repository">9.8.1. Local Git Repository</a></h4>
<div class="paragraph">
<p>Starting the server with the option <code>--git-repo=local</code> will initiate a Git repository if none exists or use the current Git repository. When initiating the local Git repository a <code>.gitignore</code> file will be created and added to the initial commit.</p>
</div>
<div class="paragraph">
<p>If a <code>--git-branch</code> parameter is added then the repository will be checked out on the supplied branch. Please note that the branch will not be automatically created and must exist in the repository already. By default, if no parameter is specified, the branch <code>master</code> will be used.</p>
</div>
</div>
<div class="sect3">
<h4 id="remote_git_repository"><a class="anchor" href="#remote_git_repository"></a><a class="link" href="#remote_git_repository">9.8.2. Remote Git Repository</a></h4>
<div class="paragraph">
<p>If a remote Git repository is provided then the server will try to pull from it at boot. If this is the first time we are pulling then local files will be deleted to avoid the pull to fail because of the need to overwrite those existing files.
The parameter for <code>--git-repo</code> can be a URL or a remote alias provided you have manually added it to the local git configuration.</p>
</div>
<div class="paragraph">
<p>If a <code>--git-branch</code> parameter is added then the branch will be pulled, otherwise it will default to <code>master</code>.</p>
</div>
<div class="paragraph">
<p>For example this is an elytron configuration file that you could use to connect to GitHub via the <code>--git-auth</code> parameter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;configuration&gt;</span>
    <span class="tag">&lt;authentication-client</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:elytron:1.0</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;authentication-rules&gt;</span>
            <span class="tag">&lt;rule</span> <span class="attribute-name">use-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;/rule&gt;</span>
        <span class="tag">&lt;/authentication-rules&gt;</span>
        <span class="tag">&lt;authentication-configurations&gt;</span>
            <span class="tag">&lt;configuration</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;sasl-mechanism-selector</span> <span class="attribute-name">selector</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">BASIC</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;set-user-name</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">ehsavoie</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;credentials&gt;</span>
                    <span class="tag">&lt;clear-password</span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">my_api_key</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
                <span class="tag">&lt;/credentials&gt;</span>
                <span class="tag">&lt;set-mechanism-realm</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">testRealm</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
            <span class="tag">&lt;/configuration&gt;</span>
        <span class="tag">&lt;/authentication-configurations&gt;</span>
    <span class="tag">&lt;/authentication-client&gt;</span>
<span class="tag">&lt;/configuration&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Sample command line to start the server using the <code>standalone-full.xml</code> file pulled from Github and being authenticated via the Elytron configuration file <code>github-wildfly-config.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./standalone.sh --git-repo=https://github.com/wildfly/wildfly-config.git --git-auth=file:///home/ehsavoie/tmp/github-wildfly-config.xml -c standalone-full.xml</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="snapshots-git-history"><a class="anchor" href="#snapshots-git-history"></a><a class="link" href="#snapshots-git-history">9.8.3. Snapshots</a></h4>
<div class="paragraph">
<p>In addition to the commits taken by the server as described above you
can manually take snapshots which will be stored as <code>tags</code> in the Git repository.
You can choose the tag name and the commit message attached to this tag.</p>
</div>
<div class="paragraph">
<p>You may also take your own snapshots using the CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :take-snapshot(name=&quot;snapshot&quot;, comment=&quot;1st snapshot&quot;)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;1st snapshot&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also use the CLI to list all the snapshots</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :list-snapshots
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;directory&quot; =&gt; &quot;&quot;,
        &quot;names&quot; =&gt; [
            &quot;snapshot : 1st snapshot&quot;,
            &quot;refs/tags/snapshot&quot;,
            &quot;snapshot2 : 2nd snapshot&quot;,
            &quot;refs/tags/snapshot2&quot;
        ]
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To delete a particular snapshot:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :delete-snapshot(name=&quot;snapshot2&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="remote_push"><a class="anchor" href="#remote_push"></a><a class="link" href="#remote_push">9.8.4. Remote push</a></h4>
<div class="paragraph">
<p>You may need to push your repository changes to a remote repository so you can share them.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] :publish-configuration(location=&quot;origin&quot;)
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="ssh_auth"><a class="anchor" href="#ssh_auth"></a><a class="link" href="#ssh_auth">9.8.5. SSH Authentication</a></h4>
<div class="paragraph">
<p>Users may also connect to an SSH git server. In order to connect to any SSH git server to manage your configuration file history, you must use an Elytron configuration
file to specify your SSH credentials. The following example shows how to specify an SSH url and a <code>wildfly-config.xml</code> file
containing SSH credentials:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./standalone.sh --git-repo=git@github.com:wildfly/wildfly-config.git --git-auth=file:///home/user/github-wildfly-config.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are a number of ways to specify your SSH credentials in the <code>wildfly-config.xml</code> file:</p>
</div>
<div class="sect4">
<h5 id="ssh-key-location-credential"><a class="anchor" href="#ssh-key-location-credential"></a><a class="link" href="#ssh-key-location-credential">SSH Key Location Credential</a></h5>
<div class="paragraph">
<p>It is possible to reference a file containing your SSH keys as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;configuration&gt;</span>
    <span class="tag">&lt;authentication-client</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:elytron:client:1.6</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;authentication-rules&gt;</span>
            <span class="tag">&lt;rule</span> <span class="attribute-name">use-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;/rule&gt;</span>
        <span class="tag">&lt;/authentication-rules&gt;</span>
        <span class="tag">&lt;authentication-configurations&gt;</span>
            <span class="tag">&lt;configuration</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;credentials&gt;</span>
                    <span class="tag">&lt;ssh-credential</span> <span class="attribute-name">ssh-directory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/home/user/git-persistence/</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">private-key-file</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">id_ec_test</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">known-hosts-file</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">known_hosts</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                        <span class="tag">&lt;clear-password</span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
                    <span class="tag">&lt;/ssh-private-key&gt;</span>
                <span class="tag">&lt;/credentials&gt;</span>
            <span class="tag">&lt;/configuration&gt;</span>
        <span class="tag">&lt;/authentication-configurations&gt;</span>
    <span class="tag">&lt;/authentication-client&gt;</span>
<span class="tag">&lt;/configuration&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This configuration indicates that the private key to be used for SSH authentication is in the file <code>id_ec_test</code> in the
directory <code>/home/user/git-persistence</code> and the passphrase "secret" is needed to decrypt the key.</p>
</div>
<div class="paragraph">
<p>The <code>ssh-credential</code> accepts the following attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>ssh-directory</code> - the path to the directory containing the private key file and the known hosts file. The default value
is <code>[user.home]/.ssh</code>.</p>
</li>
<li>
<p><code>private-key-file</code> - the name of the file containing the private key. The default private key file names used are: <code>id_rsa</code>,
<code>id_dsa</code>, and <code>id_ecdsa</code>.</p>
</li>
<li>
<p><code>known-hosts-file</code> - the name of the file containing the known SSH hosts you trust. The default value is <code>known_hosts</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>One of the following child elements may also be used to specify the passphrase to be used to decrypt the private key (if applicable):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;ssh-credential</span> <span class="attribute-name">...</span><span class="tag">&gt;</span>
    <span class="tag">&lt;credential-store-reference</span> <span class="attribute-name">store</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">alias</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">clear-text</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;clear-password</span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;masked-password</span> <span class="attribute-name">algorithm</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">key-material</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">iteration-count</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">salt</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">masked-password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">initialization-vector</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/ssh-credential&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="key-pair-credential"><a class="anchor" href="#key-pair-credential"></a><a class="link" href="#key-pair-credential">Key Pair Credential</a></h5>
<div class="paragraph">
<p>It is also possible to specify your SSH credentials as a KeyPairCredential as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;configuration&gt;</span>
    <span class="tag">&lt;authentication-client</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">urn:elytron:client:1.6</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
        <span class="tag">&lt;authentication-rules&gt;</span>
            <span class="tag">&lt;rule</span> <span class="attribute-name">use-configuration</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
            <span class="tag">&lt;/rule&gt;</span>
        <span class="tag">&lt;/authentication-rules&gt;</span>
        <span class="tag">&lt;authentication-configurations&gt;</span>
            <span class="tag">&lt;configuration</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test-login</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                <span class="tag">&lt;credentials&gt;</span>
                    <span class="tag">&lt;key-pair&gt;</span>
                        <span class="tag">&lt;openssh-private-key</span> <span class="attribute-name">pem</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">-----BEGIN OPENSSH PRIVATE KEY-----</span>
                        <span class="content">b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABCdRswttV</span>
                        <span class="content">UNQ6nKb6ojozTGAAAAEAAAAAEAAABoAAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlz</span>
                        <span class="content">dHAyNTYAAABBBAKxnsRT7n6qJLKoD3mFfAvcH5ZFUyTzJVW8t60pNgNaXO4q5S4qL9yCCZ</span>
                        <span class="content">cKyg6QtVgRuVxkUSseuR3fiubyTnkAAADQq3vrkvuSfm4n345STr/i/29FZEFUd0qD++B2</span>
                        <span class="content">ZoWGPKU/xzvxH7S2GxREb5oXcIYO889jY6mdZT8LZm6ZZig3rqoEAqdPyllHmEadb7hY+y</span>
                        <span class="content">jwcQ4Wr1ekGgVwNHCNu2in3cYXxbrYGMHc33WmdNrbGRDUzK+EEUM2cwUiM7Pkrw5s88Ff</span>
                        <span class="content">IWI0V+567Ob9LxxIUO/QvSbKMJGbMM4jZ1V9V2Ti/GziGJ107CBudZr/7wNwxIK86BBAEg</span>
                        <span class="content">hfnrhYBIaOLrtP8R+96i8iu4iZAvcIbQ==</span>
                        <span class="content">-----END OPENSSH PRIVATE KEY-----</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
                            <span class="tag">&lt;clear-password</span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">secret</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
                        <span class="tag">&lt;/openssh-private-key&gt;</span>
                    <span class="tag">&lt;/key-pair&gt;</span>
                <span class="tag">&lt;/credentials&gt;</span>
            <span class="tag">&lt;/configuration&gt;</span>
        <span class="tag">&lt;/authentication-configurations&gt;</span>
    <span class="tag">&lt;/authentication-client&gt;</span>
<span class="tag">&lt;/configuration&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Along with the <code>key-pair</code> credential, if your known SSH hosts are not in <code>~/.ssh/known_hosts</code>, you should specify an <code>ssh-credential</code>
with the <code>ssh-directory</code> and <code>known-hosts-file</code> attributes defined to specify the location and name of your known hosts file.</p>
</div>
<div class="paragraph">
<p>When specifying keys in OpenSSH format, it is only necessary to specify the private key and the public key will be parsed
from the private key string. When specifying key pairs in PKCS format, it is necessary to specify both the private and
public keys using the following elements:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;key-pair&gt;</span>
    <span class="tag">&lt;private-key-pem&gt;</span>-----BEGIN PRIVATE KEY-----
                     MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgj+ToYNaHz/pISg/Z
                     I9BjdhcTre/SJpIxASY19XtOV1ehRANCAASngcxUTBf2atGC5lQWCupsQGRNwwnK
                     6Ww9Xt37SmaHv0bX5n1KnsAal0ykJVKZsD0Z09jVF95jL6udwaKpWQwb
                     -----END PRIVATE KEY-----<span class="tag">&lt;/private-key&gt;</span>
    <span class="tag">&lt;public-key-pem&gt;</span>-----BEGIN PUBLIC KEY-----
                     MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEp4HMVEwX9mrRguZUFgrqbEBkTcMJ
                     yulsPV7d+0pmh79G1+Z9Sp7AGpdMpCVSmbA9GdPY1RfeYy+rncGiqVkMGw==
                     -----END PUBLIC KEY-----<span class="tag">&lt;/public-key&gt;</span>
<span class="tag">&lt;/key-pair&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>When using a key pair credential in OpenSSH format, it is also possible to specify a passphrase to be used to decrypt
the private key:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;openssh-private-key</span> <span class="attribute-name">pem</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;credential-store-reference</span> <span class="attribute-name">store</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">alias</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">clear-text</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;clear-password</span> <span class="attribute-name">password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
    <span class="tag">&lt;masked-password</span> <span class="attribute-name">algorithm</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">key-material</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">iteration-count</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">salt</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">masked-password</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">initialization-vector</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span> <span class="tag">/&gt;</span>
<span class="tag">&lt;/ssh-private-key-file&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>When using PKCS formatted keys, the keys should not be encrypted with a passphrase</p>
</div>
</div>
<div class="sect4">
<h5 id="credential-store-reference"><a class="anchor" href="#credential-store-reference"></a><a class="link" href="#credential-store-reference">Credential Store Reference</a></h5>
<div class="paragraph">
<p>It is possible to specify your SSH credentials as a reference to a credential store entry.
See: <a href="https://github.com/wildfly/wildfly/blob/main/docs/src/main/asciidoc/_elytron/Credential_Store.adoc#adding-a-credential">Adding a Credential</a>
to a credential store and <a href="https://github.com/wildfly/wildfly/blob/main/docs/src/main/asciidoc/_elytron/Credential_Store.adoc#referencing-credentials">Referencing Credentials</a>
stored in a credential store.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="YAML_Configuration_file"><a class="anchor" href="#YAML_Configuration_file"></a><a class="link" href="#YAML_Configuration_file">9.9. (YAML) Configuration file (Experimental))</a></h3>
<div class="paragraph">
<p>In order to provide some way to separate customization from the configuration provisionned by Galleon we want to <strong>experiment</strong> with a new feature where this customization is provided by YAML files.
Because this feature is <strong>EXPERIMENTAL</strong> we are disabling it by default and you can <strong>NOT</strong> rely on it being present or compatible in the future releases.</p>
</div>
<div class="sect3">
<h4 id="activate_yaml_feature"><a class="anchor" href="#activate_yaml_feature"></a><a class="link" href="#activate_yaml_feature">9.9.1. Active the YAML support feature</a></h4>
<div class="paragraph">
<p>To enable that feature you need to add a ServiceLoader configuration in the <code>org.jboss.as.controller</code> module.
You need to create the following file: <code>META-INF/services/org.jboss.as.controller.persistence.ConfigurationExtension</code> containing a single line <strong>org.jboss.as.controller.persistence.yaml.YamlConfigurationExtension</strong> in the dir folder of the <code>org.jboss.as.controller</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>mkdir -p $WILDFLY_HOME/modules/system/layers/base/org/jboss/as/controller/main/dir/META-INF/services/
echo 'org.jboss.as.controller.persistence.yaml.YamlConfigurationExtension' &gt; $WILDFLY_HOME/modules/system/layers/base/org/jboss/as/controller/main/dir/META-INF/services/org.jboss.as.controller.persistence.ConfigurationExtension</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="starting_with_yaml_files"><a class="anchor" href="#starting_with_yaml_files"></a><a class="link" href="#starting_with_yaml_files">9.9.2. Starting with YAML files</a></h4>
<div class="paragraph">
<p>Using the <code>--yaml</code> or <code>-y</code> argument you can pass a list of YAML files. Each path needs to be separated by the <code>File.pathSeparator</code>.  It is a semicolon (;) on Windows and colon (:) on Mac and Unix-based operating systems.
Paths can be absolute, relative to the current execution directory or relative to the standalone configuration directory.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./standalone.sh -y=/home/ehsavoie/dev/wildfly/config2.yml:config.yml -c standalone-full.xml</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="what_is_in_yaml"><a class="anchor" href="#what_is_in_yaml"></a><a class="link" href="#what_is_in_yaml">9.9.3. What is in the YAML</a></h4>
<div class="paragraph">
<p>The YAML root node must be <strong>wildfly-configuration</strong>, then you can follow the model tree to add or update resources.</p>
</div>
<div class="paragraph">
<p>Sample YAML file to define a new PostGresql datasource:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>wildfly-configuration:
  subsystem:
    datasources:
      jdbc-driver:
        postgresql:
          driver-name: postgresql
          driver-xa-datasource-class-name: org.postgresql.xa.PGXADataSource
          driver-module-name: org.postgresql.jdbc
      data-source:
        PostgreSQLDS:
          enabled: true
          exception-sorter-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
          jndi-name: java:jboss/datasources/PostgreSQLDS
          jta: true
          max-pool-size: 20
          min-pool-size: 0
          connection-url: &quot;jdbc:postgresql://localhost:5432}/demo&quot;
          driver-name: postgresql
          user-name: postgres
          password: postgres
          validate-on-match: true
          background-validation: false
          background-validation-millis: 10000
          flush-strategy: FailingConnectionOnly
          statistics-enable: false
          stale-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
          valid-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
          transaction-isolation: TRANSACTION_READ_COMMITTED</code></pre>
</div>
</div>
<div class="paragraph">
<p>We also provide three operations using tags:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>!undefine</strong>: to undefine an attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Sample YAML file to undefine the CONSOLE logger level:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>wildfly-configuration:
    subsystem:
        logging:
          console-handler:
            CONSOLE:
              level: !undefine</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>!remove</strong>: to remove the resource</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Sample YAML file to remove the MicroProfile Smallrye JWT subsystem:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>wildfly-configuration:
    subsystem:
        microprofile-jwt-smallrye: !remove</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>!list-add</strong>: to add an element to a list (with an optionnal index).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Sample YAML file to add a RemoteTransactionPermission to the permissions list at the position 0:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>wildfly-configuration:
    subsystem:
        elytron:
          permission-set:
           default-permissions:
             permissions: !list-add
              - class-name: org.wildfly.transaction.client.RemoteTransactionPermission
                module: org.wildfly.transaction.client
                target-name: &quot;*&quot;
                index: 0</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="Management_API_reference"><a class="anchor" href="#Management_API_reference"></a><a class="link" href="#Management_API_reference">10. Management API reference</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>This section is an in depth reference to the WildFly management API.
Readers are encouraged to read the
<a href="#Management_Clients">Management clients</a> and
<a href="#Core_management_concepts">Core management concepts</a> sections
for fundamental background information, as well as the
<a href="#Management_tasks">Management tasks</a> and
<a href="#Domain_Setup">Domain setup</a> sections for key task oriented
information. This section is meant as an in depth reference to delve
into some of the key details.</p>
</div>
<div class="sect2">
<h3 id="Global_operations"><a class="anchor" href="#Global_operations"></a><a class="link" href="#Global_operations">10.1. Global operations</a></h3>
<div class="paragraph">
<p>The WildFly management API includes a number of operations that apply to
every resource.</p>
</div>
<div class="sect3">
<h4 id="the-read-resource-operation"><a class="anchor" href="#the-read-resource-operation"></a><a class="link" href="#the-read-resource-operation">10.1.1. The read-resource operation</a></h4>
<div class="paragraph">
<p>Reads a management resource&#8217;s attribute values along with either basic
or complete information about any child resources. Supports the following
parameters, none of which are required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>recursive</code> – (boolean, default is <code>false</code>) – whether to include
complete information about child resources, recursively.</p>
</li>
<li>
<p><code>recursive-depth</code> – (int) – The depth to which information about child
resources should be included if <code>recursive</code> is <code>true</code>. If not set, the
depth will be unlimited; i.e. all descendant resources will be included.</p>
</li>
<li>
<p><code>proxies</code> – (boolean, default is <code>false</code>) – whether to include remote
resources in a recursive query (i.e. host level resources from secondary
Host Controllers in a query of the Domain Controller; running server
resources in a query of a host).</p>
</li>
<li>
<p><code>include-runtime</code> – (boolean, default is <code>false</code>) – whether to include
runtime attributes (i.e. those whose value does not come from the
persistent configuration) in the response.</p>
</li>
<li>
<p><code>include-defaults</code> – (boolean, default is <code>true</code>) – whether to include
in the result default values not set by users. Many attributes have a
default value that will be used in the runtime if the users have not
provided an explicit value. If this parameter is <code>false</code> the value for
such attributes in the result will be <code>undefined</code>. If <code>true</code> the result
will include the default value for such parameters.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-read-attribute-operation"><a class="anchor" href="#the-read-attribute-operation"></a><a class="link" href="#the-read-attribute-operation">10.1.2. The read-attribute operation</a></h4>
<div class="paragraph">
<p>Reads the value of an individual attribute. Takes a single, required,
parameter:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the attribute to read.</p>
</li>
<li>
<p><code>include-defaults</code> – (boolean, default is <code>true</code>) – whether to include
in the result default values not set by users. Many attributes have a
default value that will be used in the runtime if the users have not
provided an explicit value. If this parameter is <code>false</code> the value for
such attributes in the result will be <code>undefined</code>. If <code>true</code> the result
will include the default value for such parameters.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-write-attribute-operation"><a class="anchor" href="#the-write-attribute-operation"></a><a class="link" href="#the-write-attribute-operation">10.1.3. The write-attribute operation</a></h4>
<div class="paragraph">
<p>Writes the value of an individual attribute. Takes two required
parameters:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the attribute to write.</p>
</li>
<li>
<p><code>value</code> – (type depends on the attribute being written) – the new
value.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-undefine-attribute-operation"><a class="anchor" href="#the-undefine-attribute-operation"></a><a class="link" href="#the-undefine-attribute-operation">10.1.4. The undefine-attribute operation</a></h4>
<div class="paragraph">
<p>Sets the value of an individual attribute to the <code>undefined</code> value, if
such a value is allowed for the attribute. The operation will fail if
the <code>undefined</code> value is not allowed. Takes a single required parameter:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the attribute to write.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-list-add-operation"><a class="anchor" href="#the-list-add-operation"></a><a class="link" href="#the-list-add-operation">10.1.5. The list-add operation</a></h4>
<div class="paragraph">
<p>Adds an element to the value of a list attribute, adding the element to
the end of the list unless the optional attribute <code>index</code> is passed:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the list attribute to add new value
to.</p>
</li>
<li>
<p><code>value</code> – (type depends on the element being written) – the new
element to be added to the attribute value.</p>
</li>
<li>
<p><code>index</code> – (int, optional) – index where in the list to add the new
element. By default it is <code>undefined</code> meaning add at the end. Index is
zero based.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a list.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-list-remove-operation"><a class="anchor" href="#the-list-remove-operation"></a><a class="link" href="#the-list-remove-operation">10.1.6. The list-remove operation</a></h4>
<div class="paragraph">
<p>Removes an element from the value of a list attribute, either the
element at a specified <code>index</code>, or the first element whose value matches
a specified <code>value</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the list attribute to add new value
to.</p>
</li>
<li>
<p><code>value</code> – (type depends on the element being written, optional) – the
element to be removed. Optional and ignored if <code>index</code> is specified.</p>
</li>
<li>
<p><code>index</code> – (int, optional) – index in the list whose element should be
removed. By default it is <code>undefined</code>, meaning <code>value</code> should be
specified.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a list.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-list-get-operation"><a class="anchor" href="#the-list-get-operation"></a><a class="link" href="#the-list-get-operation">10.1.7. The list-get operation</a></h4>
<div class="paragraph">
<p>Gets one element from a list attribute by its index</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the list attribute</p>
</li>
<li>
<p><code>index</code> – (int, required) – index of element to get from list</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a list.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-list-clear-operation"><a class="anchor" href="#the-list-clear-operation"></a><a class="link" href="#the-list-clear-operation">10.1.8. The list-clear operation</a></h4>
<div class="paragraph">
<p>Empties the list attribute. It is different from <code>:undefine-attribute</code>
as it results in attribute of type list with 0 elements, whereas
<code>:undefine-attribute</code> results in an <code>undefined</code> value for the attribute</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the list attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a list.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-map-put-operation"><a class="anchor" href="#the-map-put-operation"></a><a class="link" href="#the-map-put-operation">10.1.9. The map-put operation</a></h4>
<div class="paragraph">
<p>Adds an key/value pair entry to the value of a map attribute:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the map attribute to add the new entry
to.</p>
</li>
<li>
<p><code>key</code> – (string) – the key of the new entry to be added.</p>
</li>
<li>
<p><code>value</code> – (type depends on the entry being written) – the value of the
new entry to be added to the attribute value.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a map.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-map-remove-operation"><a class="anchor" href="#the-map-remove-operation"></a><a class="link" href="#the-map-remove-operation">10.1.10. The map-remove operation</a></h4>
<div class="paragraph">
<p>Removes an entry from the value of a map attribute:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the map attribute to remove the new
entry from.</p>
</li>
<li>
<p><code>key</code> – (string) – the key of the entry to be removed.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a map.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-map-get-operation"><a class="anchor" href="#the-map-get-operation"></a><a class="link" href="#the-map-get-operation">10.1.11. The map-get operation</a></h4>
<div class="paragraph">
<p>Gets the value of one entry from a map attribute</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the map attribute</p>
</li>
<li>
<p><code>key</code> – (string) – the key of the entry.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a map.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-map-clear-operation"><a class="anchor" href="#the-map-clear-operation"></a><a class="link" href="#the-map-clear-operation">10.1.12. The map-clear operation</a></h4>
<div class="paragraph">
<p>Empties the map attribute. It is different from <code>:undefine-attribute</code> as
it results in attribute of type map with 0 entries, whereas
<code>:undefine-attribute</code> results in an <code>undefined</code> value for the attribute</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the map attribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This operation will fail if the specified attribute is not a map.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-read-resource-description-operation"><a class="anchor" href="#the-read-resource-description-operation"></a><a class="link" href="#the-read-resource-description-operation">10.1.13. The read-resource-description operation</a></h4>
<div class="paragraph">
<p>Returns the description of a resource&#8217;s attributes, types of children
and, optionally, operations. Supports the<br>
following parameters, none of which are required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>recursive</code> – (boolean, default is <code>false</code>) – whether to include
information about child resources, recursively.</p>
</li>
<li>
<p><code>proxies</code> – (boolean, default is <code>false</code>) – whether to include remote
resources in a recursive query (i.e. host level resources from secondary
Host Controllers in a query of the Domain Controller; running server
resources in a query of a host)</p>
</li>
<li>
<p><code>operations</code> – (boolean, default is <code>false</code>) – whether to include
descriptions of the resource&#8217;s operations</p>
</li>
<li>
<p><code>inherited</code> – (boolean, default is <code>true</code>) – if <code>operations</code> is
<code>true</code>, whether to include descriptions of operations inherited from
higher level resources. The global operations described in this section
are themselves inherited from the root resource, so the primary effect
of setting <code>inherited</code> to <code>false</code> is to exclude the descriptions of the
global operations from the output.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>See <a href="#Description_of_the_Management_Model">Description of the
Management Model</a> for details on the result of this operation.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-read-operation-names-operation"><a class="anchor" href="#the-read-operation-names-operation"></a><a class="link" href="#the-read-operation-names-operation">10.1.14. The read-operation-names operation</a></h4>
<div class="paragraph">
<p>Returns a list of the names of all the operations the resource supports.
Takes no parameters.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-read-operation-description-operation"><a class="anchor" href="#the-read-operation-description-operation"></a><a class="link" href="#the-read-operation-description-operation">10.1.15. The read-operation-description operation</a></h4>
<div class="paragraph">
<p>Returns the description of an operation, along with details of its
parameter types and its return value. Takes a single, required,
parameter:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the operation</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>See <a href="#Description_of_the_Management_Model">Description of the
Management Model</a> for details on the result of this operation.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-read-children-types-operation"><a class="anchor" href="#the-read-children-types-operation"></a><a class="link" href="#the-read-children-types-operation">10.1.16. The read-children-types operation</a></h4>
<div class="paragraph">
<p>Returns a list of the
<a href="#address"><em>types</em> of child resources</a> the resource supports. Takes two optional
parameters:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>include-aliases</code> – (boolean, default is <code>false</code>) – whether to include
alias children (i.e. those which are aliases of other sub-resources) in
the response.</p>
</li>
<li>
<p><code>include-singletons</code> – (boolean, default is <code>false</code>) – whether to
include singleton children (i.e. those are children that acts as
resource aggregate and are registered with a wildcard name) in the
response
<a href="http://lists.jboss.org/pipermail/wildfly-dev/2014-August/002701.html">wildfly-dev
discussion around this topic</a>.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-read-children-names-operation"><a class="anchor" href="#the-read-children-names-operation"></a><a class="link" href="#the-read-children-names-operation">10.1.17. The read-children-names operation</a></h4>
<div class="paragraph">
<p>Returns a list of the names of all child resources of a given
<a href="#address">type</a>.
Takes a single, required, parameter:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>child-type</code> – (string) – the name of the type</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-read-children-resources-operation"><a class="anchor" href="#the-read-children-resources-operation"></a><a class="link" href="#the-read-children-resources-operation">10.1.18. The read-children-resources operation</a></h4>
<div class="paragraph">
<p>Returns information about all of a resource&#8217;s children that are of a
given <a href="#address">type</a>.
For each child resource, the returned information is equivalent to
executing the <code>read-resource</code> operation on that resource. Takes the
following parameters, of which only \{{child-type} is required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>child-type</code> – (string) – the name of the type of child resource</p>
</li>
<li>
<p><code>recursive</code> – (boolean, default is <code>false</code>) – whether to include
complete information about child resources, recursively.</p>
</li>
<li>
<p><code>recursive-depth</code> – (int) – The depth to which information about child
resources should be included if <code>recursive</code> is \{{true}. If not set,
the depth will be unlimited; i.e. all descendant resources will be
included.</p>
</li>
<li>
<p><code>proxies</code> – (boolean, default is <code>false</code>) – whether to include remote
resources in a recursive query (i.e. host level resources from secondary
Host Controllers in a query of the Domain Controller; running server
resources in a query of a host)</p>
</li>
<li>
<p><code>include-runtime</code> – (boolean, default is <code>false</code>) – whether to include
runtime attributes (i.e. those whose value does not come from the
persistent configuration) in the response.</p>
</li>
<li>
<p><code>include-defaults</code> – (boolean, default is <code>true</code>) – whether to include
in the result default values not set by users. Many attributes have a
default value that will be used in the runtime if the users have not
provided an explicit value. If this parameter is <code>false</code> the value for
such attributes in the result will be <code>undefined</code>. If <code>true</code> the result
will include the default value for such parameters.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-read-attribute-group-operation"><a class="anchor" href="#the-read-attribute-group-operation"></a><a class="link" href="#the-read-attribute-group-operation">10.1.19. The read-attribute-group operation</a></h4>
<div class="paragraph">
<p>Returns a list of attributes of a
<a href="#address">type</a> for a given attribute group name. For each attribute the returned
information is equivalent to executing the <code>read-attribute</code> operation of
that resource. Takes the following parameters, of which only \{{name}
is required:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>name</code> – (string) – the name of the attribute group to read.</p>
</li>
<li>
<p><code>include-defaults</code> – (boolean, default is <code>true</code>) – whether to include
in the result default values not set by users. Many attributes have a
default value that will be used in the runtime if the users have not
provided an explicit value. If this parameter is <code>false</code> the value for
such attributes in the result will be <code>undefined</code>. If <code>true</code> the result
will include the default value for such parameters.</p>
</li>
<li>
<p><code>include-runtime</code> – (boolean, default is <code>false</code>) – whether to include
runtime attributes (i.e. those whose value does not come from the
persistent configuration) in the response.</p>
</li>
<li>
<p><code>include-aliases</code> – (boolean, default is <code>false</code>) – whether to include
alias attributes (i.e. those which are alias of other attributes) in the
response.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="the-read-attribute-group-names-operation"><a class="anchor" href="#the-read-attribute-group-names-operation"></a><a class="link" href="#the-read-attribute-group-names-operation">10.1.20. The read-attribute-group-names operation</a></h4>
<div class="paragraph">
<p>Returns a list of attribute groups names for a given <a href="#address">type</a>.
Takes no parameters.</p>
</div>
</div>
<div class="sect3">
<h4 id="standard-operations"><a class="anchor" href="#standard-operations"></a><a class="link" href="#standard-operations">10.1.21. Standard Operations</a></h4>
<div class="paragraph">
<p>Besides the global operations described above, by convention nearly
every resource should expose an <code>add</code> operation and a <code>remove</code>
operation. Exceptions to this convention are the root resource, and
resources that do not store persistent configuration and are created
dynamically at runtime (e.g. resources representing the JVM&#8217;s platform
mbeans or resources representing aspects of the running state of a
deployment.)</p>
</div>
<div class="sect4">
<h5 id="the-add-operation"><a class="anchor" href="#the-add-operation"></a><a class="link" href="#the-add-operation">The add operation</a></h5>
<div class="paragraph">
<p>The operation that creates a new resource must be named <code>add</code>. The
operation may take zero or more parameters; what those parameters are
depends on the resource being created.</p>
</div>
</div>
<div class="sect4">
<h5 id="the-remove-operation"><a class="anchor" href="#the-remove-operation"></a><a class="link" href="#the-remove-operation">The remove operation</a></h5>
<div class="paragraph">
<p>The operation that removes an existing resource must be named <code>remove</code>.
The operation should take no parameters.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Detyped_management_and_the_jboss-dmr_library"><a class="anchor" href="#Detyped_management_and_the_jboss-dmr_library"></a><a class="link" href="#Detyped_management_and_the_jboss-dmr_library">10.2. Detyped management and the jboss-dmr library</a></h3>
<div class="paragraph">
<p>The management model exposed by WildFly is very large and complex. There
are dozens, probably hundreds of logical concepts involved – hosts,
server groups, servers, subsystems, datasources, web connectors, and on
and on – each of which in a classic objected oriented API design could
be represented by a Java <em>type</em> (i.e. a Java class or interface.)
However, a primary goal in the development of WildFly&#8217;s native
management API was to ensure that clients built to use the API had as
few compile-time and run-time dependencies on JBoss-provided classes as
possible, and that the API exposed by those libraries be powerful but
also simple and stable. A management client running with the management
libraries created for an earlier version of WildFly should still work if
used to manage a later version domain. The management client libraries
needed to be <em>forward compatible</em>.</p>
</div>
<div class="paragraph">
<p>It is highly unlikely that an API that consists of hundreds of Java
types could be kept forward compatible. Instead, the WildFly management
API is a <em>detyped</em> API. A detyped API is like decaffeinated coffee – it
still has a little bit of caffeine, but not enough to keep you awake at
night. WildFly&#8217;s management API still has a few Java types in it (it&#8217;s
impossible for a Java library to have no types!) but not enough to keep
you (or us) up at night worrying that your management clients won&#8217;t be
forward compatible.</p>
</div>
<div class="paragraph">
<p>A detyped API works by making it possible to build up arbitrarily
complex data structures using a small number of Java types. All of the
parameter values and return values in the API are expressed using those
few types. Ideally, most of the types are basic JDK types, like
<code>java.lang.String</code>, <code>java.lang.Integer</code>, etc. In addition to the basic
JDK types, WildFly&#8217;s detyped management API uses a small library called
<strong>jboss-dmr</strong>. The purpose of this section is to provide a basic overview
of the jboss-dmr library.</p>
</div>
<div class="paragraph">
<p>Even if you don&#8217;t use jboss-dmr directly (probably the case for all but
a few users), some of the information in this section may be useful.
When you invoke operations using the application server&#8217;s Command Line
Interface, the return values are just the text representation of of a
jboss-dmr <code>ModelNode</code>. If your CLI commands require complex parameter
values, you may yourself end up writing the text representation of a
<code>ModelNode</code>. And if you use the HTTP management API, all response bodies
as well as the request body for any POST will be a JSON representation
of a <code>ModelNode</code>.</p>
</div>
<div class="paragraph">
<p>The source code for jboss-dmr is available on
<a href="https://github.com/jbossas/jboss-dmr">Github</a>. The maven coordinates for
a jboss-dmr release are <code>org.jboss.jboss-dmr:jboss-dmr</code>.</p>
</div>
<div class="sect3">
<h4 id="modelnode-and-modeltype"><a class="anchor" href="#modelnode-and-modeltype"></a><a class="link" href="#modelnode-and-modeltype">10.2.1. ModelNode and ModelType</a></h4>
<div class="paragraph">
<p>The public API exposed by jboss-dmr is very simple: just three classes,
one of which is an enum!</p>
</div>
<div class="paragraph">
<p>The primary class is <code>org.jboss.dmr.ModelNode</code>. A <code>ModelNode</code> is
essentially just a wrapper around some <em>value</em>; the value is typically
some basic JDK type. A <code>ModelNode</code> exposes a <code>getType()</code> method. This
method returns a value of type <code>org.jboss.dmr.ModelType</code>, which is an
enum of all the valid types of values. And that&#8217;s 95% of the public API;
a class and an enum. (We&#8217;ll get to the third class, <code>Property</code>, below.)</p>
</div>
<div class="sect4">
<h5 id="basic-modelnode-manipulation"><a class="anchor" href="#basic-modelnode-manipulation"></a><a class="link" href="#basic-modelnode-manipulation">Basic ModelNode manipulation</a></h5>
<div class="paragraph">
<p>To illustrate how to work with <code>ModelNode</code> s, we&#8217;ll use the
<a href="http://www.beanshell.org">Beanshell</a> scripting library. We won&#8217;t get into
many details of beanshell here; it&#8217;s a simple and intuitive tool and
hopefully the following examples are as well.</p>
</div>
<div class="paragraph">
<p>We&#8217;ll start by launching a beanshell interpreter, with the jboss-dmr
library available on the classpath. Then we&#8217;ll tell beanshell to import
all the jboss-dmr classes so they are available for use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ java -cp bsh-2.0b4.jar:jboss-dmr-1.0.0.Final.jar bsh.Interpreter
BeanShell 2.0b4 - by Pat Niemeyer (pat@pat.net)
bsh % import org.jboss.dmr.*;
bsh %</code></pre>
</div>
</div>
<div class="paragraph">
<p>Next, create a <code>ModelNode</code> and use the beanshell <code>print</code> function to
output what type it is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode node = new ModelNode();
bsh % print(node.getType());
UNDEFINED</code></pre>
</div>
</div>
<div class="paragraph">
<p>A new <code>ModelNode</code> has no value stored, so its type is
<code>ModelType.UNDEFINED</code>.</p>
</div>
<div class="paragraph">
<p>Use one of the overloaded <code>set</code> method variants to assign a node&#8217;s
value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(1);
bsh % print(node.getType());
INT
bsh % node.set(true);
bsh % print(node.getType());
BOOLEAN
bsh % node.set(&quot;Hello, world&quot;);
bsh % print(node.getType());
STRING</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use one of the <code>asXXX()</code> methods to retrieve the value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(2);
bsh % print(node.asInt());
2
bsh % node.set(&quot;A string&quot;);
bsh % print(node.asString());
A string</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>ModelNode</code> will attempt to perform type conversions when you invoke the
<code>asXXX</code> methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(1);
bsh % print(node.asString());
1
bsh % print(node.asBoolean());
true
bsh % node.set(0);
bsh % print(node.asBoolean());
false
bsh % node.set(&quot;true&quot;);
bsh % print(node.asBoolean());
true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Not all type conversions are possible:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(&quot;A string&quot;);
bsh % print(node.asInt());
// Error: // Uncaught Exception: Method Invocation node.asInt : at Line: 20 : in file: &lt;unknown file&gt; : node .asInt ( )
 
Target exception: java.lang.NumberFormatException: For input string: &quot;A string&quot;
 
java.lang.NumberFormatException: For input string: &quot;A string&quot;
 at java.lang.NumberFormatException.forInputString(NumberFormatException.java:48)
 at java.lang.Integer.parseInt(Integer.java:449)
 at java.lang.Integer.parseInt(Integer.java:499)
 at org.jboss.dmr.StringModelValue.asInt(StringModelValue.java:61)
 at org.jboss.dmr.ModelNode.asInt(ModelNode.java:117)
        ....</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>ModelNode.getType()</code> method can be used to ensure a node has an
expected value type before attempting a type conversion.</p>
</div>
<div class="paragraph">
<p>One <code>set</code> variant takes another <code>ModelNode</code> as its argument. The value
of the passed in node is copied, so there is no shared state between the
two model nodes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(&quot;A string&quot;);
bsh % ModelNode another = new ModelNode();
bsh % another.set(node);
bsh % print(another.asString());
A string
bsh % node.set(&quot;changed&quot;);
bsh % print(node.asString());
changed
bsh % print(another.asString());
A string</code></pre>
</div>
</div>
<div class="paragraph">
<p>A <code>ModelNode</code> can be cloned. Again, there is no shared state between the
original node and its clone:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode clone = another.clone();
bsh % print(clone.asString());
A string
bsh % another.set(42);
bsh % print(another.asString());
42
bsh % print(clone.asString());
A string</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the <code>protect()</code> method to make a <code>ModelNode</code> immutable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % clone.protect();
bsh % clone.set(&quot;A different string&quot;);
// Error: // Uncaught Exception: Method Invocation clone.set : at Line: 15 : in file: &lt;unknown file&gt; : clone .set ( &quot;A different string&quot; )
 
Target exception: java.lang.UnsupportedOperationException
 
java.lang.UnsupportedOperationException
 at org.jboss.dmr.ModelNode.checkProtect(ModelNode.java:1441)
 at org.jboss.dmr.ModelNode.set(ModelNode.java:351)
        ....</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="lists"><a class="anchor" href="#lists"></a><a class="link" href="#lists">Lists</a></h5>
<div class="paragraph">
<p>The above examples aren&#8217;t particularly interesting; if all we can do
with a <code>ModelNode</code> is wrap a simple Java primitive, what use is that?
However, a <code>ModelNode&#8217;s value can be more complex than a simple
primitive, and using these more complex types we can build complex data
structures. The first more complex type is `ModelType.LIST</code>.</p>
</div>
<div class="paragraph">
<p>Use the <code>add</code> methods to initialize a node&#8217;s value as a list and add to
the list:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode list = new ModelNode();
bsh % list.add(5);
bsh % list.add(10);
bsh % print(list.getType());
LIST</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use <code>asInt()</code> to find the size of the list:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(list.asInt());
2</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the overloaded <code>get</code> method variant that takes an int param to
retrieve an item. The item is returned as a <code>ModelNode</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode child = list.get(1);
bsh % print(child.asInt());
10</code></pre>
</div>
</div>
<div class="paragraph">
<p>Elements in a list need not all be of the same type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % list.add(&quot;A string&quot;);
bsh % print(list.get(1).getType());
INT
bsh % print(list.get(2).getType());
STRING</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Here&#8217;s one of the trickiest things about jboss-dmr:</strong> <em>The</em> <code>get</code>
<em>methods actually mutate state; they are not "read-only"</em>. For example,
calling <code>get</code> with an index that does not exist yet in the list will
actually create a child of type <code>ModelType.UNDEFINED</code> at that index (and
will create UNDEFINED children for any intervening indices.)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode four = list.get(4);
bsh % print(four.getType());
UNDEFINED
bsh % print(list.asInt());
6</code></pre>
</div>
</div>
<div class="paragraph">
<p>Since the <code>get</code> call always returns a <code>ModelNode</code> and never <code>null</code> it is
safe to manipulate the return value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % list.get(5).set(30);
bsh % print(list.get(5).asInt());
30</code></pre>
</div>
</div>
<div class="paragraph">
<p>That&#8217;s not so interesting in the above example, but later on with node
of type <code>ModelType.OBJECT</code> we&#8217;ll see how that kind of method chaining
can let you build up fairly complex data structures with a minimum of
code.</p>
</div>
<div class="paragraph">
<p>Use the <code>asList()</code> method to get a <code>List&lt;ModelNode&gt;</code> of the children:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % for (ModelNode element : list.asList()) {
print(element.getType());
}
INT
INT
STRING
UNDEFINED
UNDEFINED
INT</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>asString()</code> and <code>toString()</code> methods provide slightly differently
formatted text representations of a <code>ModelType.LIST</code> node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(list.asString());
[5,10,&quot;A string&quot;,undefined,undefined,30]
bsh % print(list.toString());
[
    5,
    10,
    &quot;A string&quot;,
    undefined,
    undefined,
    30
]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, if you&#8217;ve previously used <code>set</code> to assign a node&#8217;s value to
some non-list type, you cannot use the <code>add</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.add(5);
// Error: // Uncaught Exception: Method Invocation node.add : at Line: 18 : in file: &lt;unknown file&gt; : node .add ( 5 )
 
Target exception: java.lang.IllegalArgumentException
 
java.lang.IllegalArgumentException
 at org.jboss.dmr.ModelValue.addChild(ModelValue.java:120)
 at org.jboss.dmr.ModelNode.add(ModelNode.java:1007)
 at org.jboss.dmr.ModelNode.add(ModelNode.java:761)
        ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can, however, use the <code>setEmptyList()</code> method to change the node&#8217;s
type, and then use <code>add</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.setEmptyList();
bsh % node.add(5);
bsh % print(node.toString());
[5]</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="dmr-properties"><a class="anchor" href="#dmr-properties"></a><a class="link" href="#dmr-properties">Properties</a></h5>
<div class="paragraph">
<p>The third public class in the jboss-dmr library is
<code>org.jboss.dmr.Property</code>. A <code>Property</code> is a <code>String &#8658; ModelNode</code> tuple.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % Property prop = new Property(&quot;stuff&quot;, list);
bsh % print(prop.toString());
org.jboss.dmr.Property@79a5f739
bsh % print(prop.getName());
stuff
bsh % print(prop.getValue());
[
    5,
    10,
    &quot;A string&quot;,
    undefined,
    undefined,
    30
]</code></pre>
</div>
</div>
<div class="paragraph">
<p>The property can be passed to <code>ModelNode.set</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % node.set(prop);
bsh % print(node.getType());
PROPERTY</code></pre>
</div>
</div>
<div class="paragraph">
<p>The text format for a node of <code>ModelType.PROPERTY</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(node.toString());
(&quot;stuff&quot; =&gt; [
    5,
    10,
    &quot;A string&quot;,
    undefined,
    undefined,
    30
])</code></pre>
</div>
</div>
<div class="paragraph">
<p>Directly instantiating a <code>Property</code> via its constructor is not common.
More typically one of the two argument <code>ModelNode.add</code> or
<code>ModelNode.set</code> variants is used. The first argument is the property
name:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode simpleProp = new ModelNode();
bsh % simpleProp.set(&quot;enabled&quot;, true);
bsh % print(simpleProp.toString());
(&quot;enabled&quot; =&gt; true)
bsh % print(simpleProp.getType());
PROPERTY
bsh % ModelNode propList = new ModelNode();
bsh % propList.add(&quot;min&quot;, 1);
bsh % propList.add(&quot;max&quot;, 10);
bsh % print(propList.toString());
[
    (&quot;min&quot; =&gt; 1),
    (&quot;max&quot; =&gt; 10)
]
bsh % print(propList.getType());
LIST
bsh % print(propList.get(0).getType());
PROPERTY</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>asPropertyList()</code> method provides easy access to a
<code>List&lt;Property&gt;</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % for (Property prop : propList.asPropertyList()) {
print(prop.getName() + &quot; = &quot; + prop.getValue());
}
min = 1
max = 10</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="modeltype.object"><a class="anchor" href="#modeltype.object"></a><a class="link" href="#modeltype.object">ModelType.OBJECT</a></h5>
<div class="paragraph">
<p>The most powerful and most commonly used complex value type in jboss-dmr
is <code>ModelType.OBJECT</code>. A <code>ModelNode</code> whose value is <code>ModelType.OBJECT</code>
internally maintains a <code>Map&lt;String, ModelNode</code>.</p>
</div>
<div class="paragraph">
<p>Use the <code>get</code> method variant that takes a string argument to add an
entry to the map. If no entry exists under the given name, a new entry
is added with a the value being a <code>ModelType.UNDEFINED</code> node. The node
is returned:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode range = new ModelNode();
bsh % ModelNode min = range.get(&quot;min&quot;);
bsh % print(range.toString());
{&quot;min&quot; =&gt; undefined}
bsh % min.set(2);
bsh % print(range.toString());
{&quot;min&quot; =&gt; 2}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Again <strong>it is important to remember that the</strong> <code>get</code> <strong>operation may mutate
the state of a model node by adding a new entry.</strong> <em>It is not a read-only
operation.</em></p>
</div>
<div class="paragraph">
<p>Since <code>get</code> will never return <code>null</code>, a common pattern is to use method
chaining to create the key/value pair:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % range.get(&quot;max&quot;).set(10);
bsh % print(range.toString());
{
    &quot;min&quot; =&gt; 2,
    &quot;max&quot; =&gt; 10
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A call to <code>get</code> passing an already existing key will of course return
the same model node as was returned the first time <code>get</code> was called with
that key:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(min == range.get(&quot;min&quot;));
true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Multiple parameters can be passed to <code>get</code>. This is a simple way to
traverse a tree made up of <code>ModelType.OBJECT</code> nodes. Again, <code>get</code> may
mutate the node on which it is invoked; e.g. it will actually create the
tree if nodes do not exist. This next example uses a workaround to get
beanshell to handle the overloaded <code>get</code> method that takes a variable
number of arguments:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % String[] varargs = { &quot;US&quot;, &quot;Missouri&quot;, &quot;St. Louis&quot; };
bsh % salesTerritories.get(varargs).set(&quot;Brian&quot;);
bsh % print(salesTerritories.toString());
{&quot;US&quot; =&gt; {&quot;Missouri&quot; =&gt; {&quot;St. Louis&quot; =&gt; &quot;Brian&quot;}}}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The normal syntax would be:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>salesTerritories.get("US", "Missouri", "St. Louis").set("Brian");</pre>
</div>
</div>
<div class="paragraph">
<p>The key/value pairs in the map can be accessed as a <code>List&lt;Property</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % for (Property prop : range.asPropertyList()) {
print(prop.getName() + &quot; = &quot; + prop.getValue());
}
min = 2</code></pre>
</div>
</div>
<div class="paragraph">
<p>The semantics of the backing map in a node of <code>ModelType.OBJECT</code> are
those of a <code>LinkedHashMap</code>. The map remembers the order in which
key/value pairs are added. This is relevant when iterating over the
pairs after calling <code>asPropertyList()</code> and for controlling the order in
which key/value pairs appear in the output from <code>toString()</code>.</p>
</div>
<div class="paragraph">
<p>Since the <code>get</code> method will actually mutate the state of a node if the
given key does not exist, <code>ModelNode</code> provides a couple methods to let
you check whether the entry is there. The <code>has</code> method simply does that:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(range.has(&quot;unit&quot;));
false
bsh % print(range.has(&quot;min&quot;));
true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Very often, the need is to not only know whether the key/value pair
exists, but whether the value is defined (i.e. not
<code>ModelType.UNDEFINED</code>. This kind of check is analogous to checking
whether a field in a Java class has a null value. The <code>hasDefined</code> lets
you do this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(range.hasDefined(&quot;unit&quot;));
false
bsh % // Establish an undefined child 'unit';
bsh % range.get(&quot;unit&quot;);
bsh % print(range.toString());
{
    &quot;min&quot; =&gt; 2,
    &quot;max&quot; =&gt; 10,
    &quot;unit&quot; =&gt; undefined
}
bsh % print(range.hasDefined(&quot;unit&quot;));
false
bsh % range.get(&quot;unit&quot;).set(&quot;meters&quot;);
bsh % print(range.hasDefined(&quot;unit&quot;));
true</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="modeltype.expression"><a class="anchor" href="#modeltype.expression"></a><a class="link" href="#modeltype.expression">ModelType.EXPRESSION</a></h5>
<div class="paragraph">
<p>A value of type <code>ModelType.EXPRESSION</code> is stored as a string, but can
later be <em>resolved</em> to different value. The string has a special syntax
that should be familiar to those who have used the system property
substitution feature in previous JBoss AS releases.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[&lt;prefix&gt;][${&lt;system-property-name&gt;[:&lt;default-value&gt;]}][&lt;suffix&gt;]*</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>${queue.length}
http://${host}
http://${host:localhost}:${port:8080}/index.html</pre>
</div>
</div>
<div class="paragraph">
<p>Use the <code>setExpression</code> method to set a node&#8217;s value to type expression:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode expression = new ModelNode();
bsh % expression.setExpression(&quot;${queue.length}&quot;);
bsh % print(expression.getType());
EXPRESSION</code></pre>
</div>
</div>
<div class="paragraph">
<p>Calling <code>asString()</code> returns the same string that was input:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(expression.asString());
${queue.length}</code></pre>
</div>
</div>
<div class="paragraph">
<p>However, calling <code>toString()</code> tells you that this node&#8217;s value is not of
<code>ModelType.STRING</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(expression.toString());
expression &quot;${queue.length}&quot;</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the <code>resolve</code> operation is called, the string is parsed and any
embedded system properties are resolved against the JVM&#8217;s current system
property values. A new <code>ModelNode</code> is returned whose value is the
resolved string:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % System.setProperty(&quot;queue.length&quot;, &quot;10&quot;);
bsh % ModelNode resolved = expression.resolve();
bsh % print(resolved.asInt());
10</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the type of the <code>ModelNode</code> returned by <code>resolve()</code> is
<code>ModelType.STRING</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % print(resolved.getType());
STRING</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>resolved.asInt()</code> call in the previous example only worked because
the string "10" happens to be convertible into the int 10.</p>
</div>
<div class="paragraph">
<p>Calling <code>resolve()</code> has no effect on the value of the node on which the
method is invoked:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % resolved = expression.resolve();
bsh % print(resolved.toString());
&quot;10&quot;
bsh % print(expression.toString());
expression &quot;${queue.length}&quot;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If an expression cannot be resolved, <code>resolve</code> just uses the original
string. The string can include more than one system property
substitution:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % expression.setExpression(&quot;http://${host}:${port}/index.html&quot;);
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
http://${host}:${port}/index.html</code></pre>
</div>
</div>
<div class="paragraph">
<p>The expression can optionally include a default value, separated from
the name of the system property by a colon:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % expression.setExpression(&quot;http://${host:localhost}:${port:8080}/index.html&quot;);
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
http://localhost:8080/index.html</code></pre>
</div>
</div>
<div class="paragraph">
<p>Actually including a system property substitution in the expression is
not required:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % expression.setExpression(&quot;no system property&quot;);
bsh % resolved = expression.resolve();
bsh % print(resolved.asString());
no system property
bsh % print(expression.toString());
expression &quot;no system property&quot;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>resolve</code> method works on nodes of other types as well; it returns a
copy without attempting any real resolution:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode basic = new ModelNode();
bsh % basic.set(10);
bsh % resolved = basic.resolve();
bsh % print(resolved.getType());
INT
bsh % resolved.set(5);
bsh % print(resolved.asInt());
5
bsh % print(basic.asInt());
10</code></pre>
</div>
</div>
<div class="paragraph">
<p>In addition to system properties, in the above examples, we also support substituting
from environment variables. See the <a href="#Expression_Resolution">Expression Resolution</a>
subsection for a more thorough description of how this works in practice.</p>
</div>
</div>
<div class="sect4">
<h5 id="modeltype.type"><a class="anchor" href="#modeltype.type"></a><a class="link" href="#modeltype.type">ModelType.TYPE</a></h5>
<div class="paragraph">
<p>You can also pass one of the values of the <code>ModelType</code> enum to <code>set</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>bsh % ModelNode type = new ModelNode();
bsh % type.set(ModelType.LIST);
bsh % print(type.getType());
TYPE
bsh % print(type.toString());
LIST</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is useful when using a <code>ModelNode</code> data structure to describe
another <code>ModelNode</code> data structure.</p>
</div>
</div>
<div class="sect4">
<h5 id="full-list-of-modelnode-types"><a class="anchor" href="#full-list-of-modelnode-types"></a><a class="link" href="#full-list-of-modelnode-types">Full list of ModelNode types</a></h5>
<div class="paragraph">
<p>BIG_DECIMAL<br>
BIG_INTEGER<br>
BOOLEAN<br>
BYTES<br>
DOUBLE<br>
EXPRESSION<br>
INT<br>
LIST<br>
LONG<br>
OBJECT<br>
PROPERTY<br>
STRING<br>
TYPE<br>
UNDEFINED</p>
</div>
</div>
<div class="sect4">
<h5 id="text-representation-of-a-modelnode"><a class="anchor" href="#text-representation-of-a-modelnode"></a><a class="link" href="#text-representation-of-a-modelnode">Text representation of a ModelNode</a></h5>
<div class="paragraph">
<p>TODO – document the grammar</p>
</div>
</div>
<div class="sect4">
<h5 id="json-representation-of-a-modelnode"><a class="anchor" href="#json-representation-of-a-modelnode"></a><a class="link" href="#json-representation-of-a-modelnode">JSON representation of a ModelNode</a></h5>
<div class="paragraph">
<p>TODO – document the grammar</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Description_of_the_Management_Model"><a class="anchor" href="#Description_of_the_Management_Model"></a><a class="link" href="#Description_of_the_Management_Model">10.3. Description of the Management Model</a></h3>
<div class="paragraph">
<p>A detailed description of the resources, attributes and operations that
make up the management model provided by an individual WildFly instance
or by any Domain Controller or secondary Host Controller process can be
queried using the <code>read-resource-description</code>, <code>read-operation-names</code>,
<code>read-operation-description</code> and <code>read-child-types</code> operations described
in the <a href="#Global_operations">Global operations</a> section. In this
section we provide details on what&#8217;s included in those descriptions.</p>
</div>
<div class="sect3">
<h4 id="description-of-the-wildfly-managed-resources"><a class="anchor" href="#description-of-the-wildfly-managed-resources"></a><a class="link" href="#description-of-the-wildfly-managed-resources">10.3.1. Description of the WildFly Managed Resources</a></h4>
<div class="paragraph">
<p>All portions of the management model exposed by WildFly are addressable
via an ordered list of key/value pairs. For each addressable
<a href="#management-resources">Management Resource</a>, the following
descriptive information will be available:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>description</code> – String – text description of this portion of the model</p>
</li>
<li>
<p><code>min-occurs</code> – int, either 0 or 1 – Minimum number of resources of
this type that must exist in a valid model. If not present, the default
value is 0.</p>
</li>
<li>
<p><code>max-occurs</code> – int – Maximum number of resources of this type that may
exist in a valid model. If not present, the default value depends upon
the value of the final key/value pair in the address of the described
resource. If this value is '*', the default value is Integer.MAX_VALUE,
i.e. there is no limit. If this value is some other string, the default
value is 1.</p>
</li>
<li>
<p><code>attributes</code> – Map of String (the attribute name) to complex structure
– the configuration attributes available in this portion of the model.
See the <a href="#description-of-an-attribute">Description of an Attribute</a> section
for the representation of each attribute.</p>
</li>
<li>
<p><code>operations</code> – Map of String (the operation name) to complex structure
– the operations that can be targeted at this address. See the
<a href="#description-of-an-operation">Description of an Operation</a> section
for the representation of each operation.</p>
</li>
<li>
<p><code>children</code> – Map of String (the type of child) to complex structure –
the relationship of this portion of the model to other addressable
portions of the model. See the
<a href="#description-of-parentchild-relationships">Description of Parent/Child Relationships</a>
section for the representation of each child relationship.</p>
</li>
<li>
<p><code>head-comment-allowed</code> – boolean – This description key is for
possible future use.</p>
</li>
<li>
<p><code>tail-comment-allowed</code> – boolean – This description key is for
possible future use.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     &quot;description =&gt; &quot;A manageable resource&quot;,
     &quot;tail-comment-allowed&quot; =&gt; false,
     &quot;attributes&quot; =&gt; {
          &quot;foo&quot; =&gt; {
               .... details of attribute foo
          }
      },
     &quot;operations&quot; =&gt; {
          &quot;start&quot; =&gt; {
               .... details of the start operation
          }
      },
     &quot;children&quot; =&gt; {
          &quot;bar&quot; =&gt; {
               .... details of the relationship with children of type &quot;bar&quot;
          }
      }
}</code></pre>
</div>
</div>
<div class="sect4">
<h5 id="description-of-an-attribute"><a class="anchor" href="#description-of-an-attribute"></a><a class="link" href="#description-of-an-attribute">Description of an Attribute</a></h5>
<div class="paragraph">
<p>An attribute is a portion of the management model that is not directly
addressable. Instead, it is conceptually a property of an addressable
<a href="#management-resources">management resource</a>. For
each attribute in the model, the following descriptive information will
be available:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>description</code> – String – text description of the attribute</p>
</li>
<li>
<p><code>type</code> – <code>org.jboss.dmr.ModelType</code> – the type of the attribute value.
One of the enum values BIG_DECIMAL, BIG_INTEGER, BOOLEAN, BYTES, DOUBLE,
INT, LIST, LONG, OBJECT, PROPERTY, STRING. Most of these are
self-explanatory. An OBJECT will be represented in the detyped model as
a map of string keys to values of some other legal type, conceptually
similar to a <code>javax.management.openmbean.CompositeData</code>. A PROPERTY is a
single key/value pair, where the key is a string, and the value is of
some other legal type.</p>
</li>
<li>
<p><code>value-type</code> – ModelType or complex structure – Only present if type
is LIST or OBJECT. If all elements in the LIST or all the values of the
OBJECT type are of the same type, this will be one of the ModelType
enums BIG_DECIMAL, BIG_INTEGER, BOOLEAN, BYTES, DOUBLE, INT, LONG,
STRING. Otherwise, <code>value-type</code> will detail the structure of the
attribute value, enumerating the value&#8217;s fields and the type of their
value. So, an attribute with a <code>type</code> of LIST and a <code>value-type</code> value
of <code>ModelType.STRING</code> is analogous to a Java <code>List&lt;String&gt;</code>, while one
with a <code>value-type</code> value of <code>ModelType.INT</code> is analogous to a Java
<code>List&lt;Integer&gt;</code>. An attribute with a <code>type</code> of OBJECT and a <code>value-type</code>
value of <code>ModelType.STRING</code> is analogous to a Java
<code>Map&lt;String, String&gt;</code>. An attribute with a <code>type</code> of OBJECT and a
<code>value-type</code> whose value is not of type <code>ModelType</code> represents a
fully-defined complex object, with the object&#8217;s legal fields and their
values described.</p>
</li>
<li>
<p><code>expressions-allowed</code> – boolean – indicates whether the value of the
attribute may be of type <code>ModelType.EXPRESSION</code>, instead of its standard
type (see <code>type</code> and <code>value-type</code> above for discussion of an attribute&#8217;s
standard type.) A value of ModelType.EXPRESSION contains a
system-property or environment variable
substitution expression that the server will resolve
against the server-side system property map before using the value. For
example, an attribute named max-threads may have an expression value of
<code>${example.pool.max-threads:10</code>} instead of just 10. Default value if
not present is false.
See the <a href="#Expression_Resolution">Expression Resolution</a> subsection
for a more thorough description.</p>
</li>
<li>
<p><code>required</code> – boolean – true if the attribute must have a defined value
in a representation of its portion of the model unless another attribute
included in a list of <code>alternatives</code> is defined; false if it may be
undefined (implying a null value) even in the absence of alternatives.
If not present, true is the default.</p>
</li>
<li>
<p><code>nillable</code> – boolean – true if the attribute might not have a defined
value in a representation of its portion of the model. A nillable
attribute may<br>
be undefined either because it is not <code>required</code> or because it is
required but has <code>alternatives</code> and one of the alternatives is defined.</p>
</li>
<li>
<p><code>storage</code> – String – Either "configuration" or "runtime". If
"configuration", the attribute&#8217;s value is stored as part of the
persistent configuration (e.g. in domain.xml, host.xml or
standalone.xml.) If "runtime" the attribute&#8217;s value is not stored in the
persistent configuration; the value only exists as long as the resource
is running.</p>
</li>
<li>
<p><code>access-type</code> – String – One of "read-only", "read-write" or "metric".
Whether an attribute value can be written, or can only read. A "metric"
is a read-only attribute whose value is not stored in the persistent
configuration, and whose value may change due to activity on the server.
If an attribute is "read-write", the resource will expose an operation
named "write-attribute" whose "name" parameter will accept this
attribute&#8217;s name and whose "value" parameter will accept a valid value
for this attribute. That operation will be the standard means of
updating this attribute&#8217;s value.</p>
</li>
<li>
<p><code>restart-required</code> – String – One of "no-services", "all-services",
"resource-services" or "jvm". Only relevant to attributes whose
access-type is read-write. Indicates whether execution of a
write-attribute operation whose name parameter specifies this attribute
requires a restart of services (or an entire JVM) in order for the
change to take effect in the runtime . See the discussion of
<a href="#applying-updates-to-runtime-services">Applying
Updates to Runtime Services</a> below. Default value is "no-services".</p>
</li>
<li>
<p><code>default</code> – the default value for the attribute that will be used in
runtime services if the attribute is not explicitly defined and no other
attributes listed as <code>alternatives</code> are defined.</p>
</li>
<li>
<p><code>alternatives</code> – List of string – Indicates an exclusive relationship
between attributes. If this attribute is defined, the other attributes
listed in this descriptor&#8217;s value should be undefined, even if their
<code>required</code> descriptor says true; i.e. the presence of this attribute
satisfies the requirement. Note that an attribute that is not explicitly
configured but has a <code>default</code> value is still regarded as not being
defined for purposes of checking whether the exclusive relationship has
been violated. Default is undefined; i.e. this does not apply to most
attributes.</p>
</li>
<li>
<p><code>requires</code> – List of string – Indicates that if this attribute has a
value (other than undefined), the other attributes listed in this
descriptor&#8217;s value must also have a value, even if their required
descriptor says false. This would typically be used in conjunction with
alternatives. For example, attributes "a" and "b" are required, but are
alternatives to each other; "c" and "d" are optional. But "b" requires
"c" and "d", so if "b" is used, "c" and "d" must also be defined.
Default is undefined; i.e. this does not apply to most attributes.</p>
</li>
<li>
<p><code>capability-reference</code> – string – if defined indicates that this
attribute&#8217;s value specifies the dynamic portion of the name of the
specified capability provided by another resource. This indicates the
attribute is a reference to another area of the management model. (Note
that at present some attributes that reference other areas of the model
may not provide this information.)</p>
</li>
<li>
<p><code>head-comment-allowed</code> – boolean – This description key is for
possible future use.</p>
</li>
<li>
<p><code>tail-comment-allowed</code> – boolean – This description key is for
possible future use.</p>
</li>
<li>
<p>arbitrary key/value pairs that further describe the attribute value,
e.g. "max" &#8658; 2. See the <a href="#arbitrary-descriptors">Arbitrary
Descriptors</a> section.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Some examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>&quot;foo&quot; =&gt; {
     &quot;description&quot; =&gt; &quot;The foo&quot;,
     &quot;type&quot; =&gt; INT,
     &quot;max&quot; =&gt; 2
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>&quot;bar&quot; =&gt; {
     &quot;description&quot; =&gt; &quot;The bar&quot;,
     &quot;type&quot; =&gt; OBJECT,
     &quot;value-type&quot; =&gt; {
          &quot;size&quot; =&gt; INT,
          &quot;color&quot; =&gt; STRING
     }
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="description-of-an-operation"><a class="anchor" href="#description-of-an-operation"></a><a class="link" href="#description-of-an-operation">Description of an Operation</a></h5>
<div class="paragraph">
<p>A management resource may have operations associated with it. The
description of an operation will include the following information:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>operation-name</code> – String – the name of the operation</p>
</li>
<li>
<p><code>description</code> – String – text description of the operation</p>
</li>
<li>
<p><code>request-properties</code> – Map of String to complex structure –
description of the parameters of the operation. Keys are the names of
the parameters, values are descriptions of the parameter value types.
See
<a href="#description-of-an-operation-parameter-or-return-value">below</a>
for details on the description of parameter value types.</p>
</li>
<li>
<p><code>reply-properties</code> – complex structure, or empty – description of the
return value of the operation, with an empty node meaning void. See
<a href="#description-of-an-operation-parameter-or-return-value">below</a>
for details on the description of operation return value types.</p>
</li>
<li>
<p><code>restart-required</code> – String – One of "no-services", "all-services",
"resource-services" or "jvm". Indicates whether the operation makes a
configuration change that requires a restart of services (or an entire
JVM) in order for the change to take effect in the runtime. See
the discussion of <a href="#applying-updates-to-runtime-services">Applying
Updates to Runtime Services</a> below. Default value is "no-services".</p>
</li>
</ul>
</div>
<div class="sect5">
<h6 id="description-of-an-operation-parameter-or-return-value"><a class="anchor" href="#description-of-an-operation-parameter-or-return-value"></a><a class="link" href="#description-of-an-operation-parameter-or-return-value">Description of an Operation Parameter or Return Value</a></h6>
<div class="ulist">
<ul>
<li>
<p><code>description</code> – String – text description of the parameter or return
value</p>
</li>
<li>
<p><code>type</code> – <code>org.jboss.dmr.ModelType</code> – the type of the parameter or
return value. One of the enum values BIG_DECIMAL, BIG_INTEGER, BOOLEAN,
BYTES, DOUBLE, INT, LIST, LONG, OBJECT, PROPERTY, STRING.</p>
</li>
<li>
<p><code>value-type</code> – <code>ModelType</code> or complex structure – Only present if type
is LIST or OBJECT. If all elements in the LIST or all the values of the
OBJECT type are of the same type, this will be one of the ModelType
enums BIG_DECIMAL, BIG_INTEGER, BOOLEAN, BYTES, DOUBLE, INT, LIST, LONG,
PROPERTY, STRING. Otherwise, value-type will detail the structure of the
attribute value, enumerating the value&#8217;s fields and the type of their
value.So, a parameter with a <code>type</code> of LIST and a <code>value-type</code> value of
<code>ModelType.STRING</code> is analogous to a Java <code>List&lt;String&gt;</code>, while one with
a <code>value-type</code> value of <code>ModelType.INT</code> is analogous to a Java
<code>List&lt;Integer&gt;</code>. A parameter with a <code>type</code> of OBJECT and a <code>value-type</code>
value of <code>ModelType.STRING</code> is analogous to a Java
<code>Map&lt;String, String&gt;</code>. A parameter with a <code>type</code> of OBJECT and a
<code>value-type</code> whose value is not of type <code>ModelType</code> represents a
fully-defined complex object, with the object&#8217;s legal fields and their
values described.</p>
</li>
<li>
<p><code>expressions-allowed</code> – boolean – indicates whether the value of the
the parameter or return value may be of type <code>ModelType.EXPRESSION</code>,
instead its standard type (see type and value-type above for discussion
of the standard type.) A value of ModelType.EXPRESSION contains a
system-property or environment variable
substitution expression that the server will resolve
against the server-side system property map before using the value. For
example, a parameter named max-threads may have an expression value of
<code>${example.pool.max-threads:10</code>} instead of just 10. Default value if
not present is false.
See the <a href="#Expression_Resolution">Expression Resolution</a> subsection
for a more thorough description.</p>
</li>
<li>
<p><code>required</code> – boolean – true if the parameter or return value must have
a defined value in the operation or response unless another item
included in a list of <code>alternatives</code> is defined; false if it may be
undefined (implying a null value) even in the absence of alternatives.
If not present, true is the default.</p>
</li>
<li>
<p><code>nillable</code> – boolean – true if the parameter or return value might not
have a defined value in a representation of its portion of the model. A
nillable parameter or return value may be undefined either because it is
not <code>required</code> or because it is required but has <code>alternatives</code> and one
of the alternatives is defined.</p>
</li>
<li>
<p><code>default</code> – the default value for the parameter that will be used in
runtime services if the parameter is not explicitly defined and no other
parameters listed as <code>alternatives</code> are defined.</p>
</li>
<li>
<p><code>restart-required</code> – String – One of "no-services", "all-services",
"resource-services" or "jvm". Only relevant to attributes whose
access-type is read-write. Indicates whether execution of a
write-attribute operation whose name parameter specifies this attribute
requires a restart of services (or an entire JVM) in order for the
change to take effect in the runtime . See the discussion of
<a href="#applying-updates-to-runtime-services">Applying
Updates to Runtime Services</a> below. Default value is "no-services".</p>
</li>
<li>
<p><code>alternatives</code> – List of string – Indicates an exclusive relationship
between parameters. If this attribute is defined, the other parameters
listed in this descriptor&#8217;s value should be undefined, even if their
required descriptor says true; i.e. the presence of this parameter
satisfies the requirement. Note that an parameer that is not explicitly
configured but has a <code>default</code> value is still regarded as not being
defined for purposes of checking whether the exclusive relationship has
been violated. Default is undefined; i.e. this does not apply to most
parameters.</p>
</li>
<li>
<p><code>requires</code> – List of string – Indicates that if this parameter has a
value (other than undefined), the other parameters listed in this
descriptor&#8217;s value must also have a value, even if their required
descriptor says false. This would typically be used in conjunction with
alternatives. For example, parameters "a" and "b" are required, but are
alternatives to each other; "c" and "d" are optional. But "b" requires
"c" and "d", so if "b" is used, "c" and "d" must also be defined.
Default is undefined; i.e. this does not apply to most parameters.</p>
</li>
<li>
<p>arbitrary key/value pairs that further describe the attribute value,
e.g. "max" &#8658;2. See the <a href="#arbitrary-descriptors">Arbitrary Descriptors</a>
section.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect4">
<h5 id="arbitrary-descriptors"><a class="anchor" href="#arbitrary-descriptors"></a><a class="link" href="#arbitrary-descriptors">Arbitrary Descriptors</a></h5>
<div class="paragraph">
<p>The description of an attribute, operation parameter or operation return
value type can include arbitrary key/value pairs that provide extra
information. Whether a particular key/value pair is present depends on
the context, e.g. a pair with key "max" would probably only occur as
part of the description of some numeric type.</p>
</div>
<div class="paragraph">
<p>Following are standard keys and their expected value type. If descriptor
authors want to add an arbitrary key/value pair to some descriptor and
the semantic matches the meaning of one of the following items, the
standard key/value type must be used.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>min</code> – int – the minimum value of some numeric type. The absence of
this item implies there is no minimum value.</p>
</li>
<li>
<p><code>max</code> – int – the maximum value of some numeric type. The absence of
this item implies there is no maximum value.</p>
</li>
<li>
<p><code>min-length</code> – int – the minimum length of some string, list or byte[]
type. The absence of this item implies a minimum length of zero.</p>
</li>
<li>
<p><code>max-length</code> – int – the maximum length of some string, list or
byte[]. The absence of this item implies there is no maximum value.</p>
</li>
<li>
<p><code>allowed</code> – List – a list of legal values. The type of the elements in
the list should match the type of the attribute.</p>
</li>
<li>
<p><code>unit</code> - The unit of the value, if one is applicable - e.g. ns, ms, s,
m, h, KB, MB, TB. See the
<code>org.jboss.as.controller.client.helpers.MeasurementUnit</code> in the
org.jboss.as:jboss-as-controller-client artifact for a listing of legal
measurement units..</p>
</li>
<li>
<p><code>filesystem-path</code> – boolean – a flag to indicate that the attribute is a
path on the filesystem.</p>
</li>
<li>
<p><code>attached-streams</code> – boolean – a flag to indicate that the attribute is a
stream id to an attached stream.</p>
</li>
<li>
<p><code>relative-to</code> – boolean – a flag to indicate that the attribute is a
relative path.</p>
</li>
<li>
<p><code>feature-reference</code> – boolean – a flag to indicate that the attribute is a
reference to a provisioning feature via a capability.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Some examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     &quot;operation-name&quot; =&gt; &quot;incrementFoo&quot;,
     &quot;description&quot; =&gt; &quot;Increase the value of the 'foo' attribute by the given amount&quot;,
     &quot;request-properties&quot; =&gt; {
          &quot;increment&quot; =&gt; {
               &quot;type&quot; =&gt; INT,
               &quot;description&quot; =&gt; &quot;The amount to increment&quot;,
               &quot;required&quot; =&gt; true
     }},
     &quot;reply-properties&quot; =&gt; {
               &quot;type&quot; =&gt; INT,
               &quot;description&quot; =&gt; &quot;The new value&quot;,
     }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     &quot;operation-name&quot; =&gt; &quot;start&quot;,
     &quot;description&quot; =&gt; &quot;Starts the thing&quot;,
     &quot;request-properties&quot; =&gt; {},
     &quot;reply-properties&quot; =&gt; {}
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="description-of-parentchild-relationships"><a class="anchor" href="#description-of-parentchild-relationships"></a><a class="link" href="#description-of-parentchild-relationships">Description of Parent/Child Relationships</a></h5>
<div class="paragraph">
<p>The address used to target an addressable portion of the model must be
an ordered list of key value pairs. The effect of this requirement is
the addressable portions of the model naturally form a tree structure,
with parent nodes in the tree defining what the valid keys are and the
children defining what the valid values are. The parent node also
defines the cardinality of the relationship. The description of the
parent node includes a children element that describes these
relationships:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     ....
     &quot;children&quot; =&gt; {
          &quot;connector&quot; =&gt; {
               .... description of the relationship with children of type &quot;connector&quot;
          },
          &quot;virtual-host&quot; =&gt; {
               .... description of the relationship with children of type &quot;virtual-host&quot;
          }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The description of each relationship will include the following
elements:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>description</code> – String – text description of the relationship</p>
</li>
<li>
<p><code>model-description</code> – either "undefined" or a complex structure – This
is a node of ModelType.OBJECT, the keys of which are legal values for
the value portion of the address of a resource of this type, with the
special character '*' indicating the value portion can have an arbitrary
value. The values in the node are the full description of the particular
child resource (its text description, attributes, operations, children)
as detailed above. This <code>model-description</code> may also be "undefined",
i.e. a null value, if the query that asked for the parent node&#8217;s
description did not include the "recursive" param set to true.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Example with if the recursive flag was set to true:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     &quot;description&quot; =&gt; &quot;The connectors used to handle client connections&quot;,
     &quot;model-description&quot; =&gt; {
          &quot;*&quot; =&gt; {
              &quot;description&quot; =&gt; &quot;Handles client connections&quot;,
              &quot;min-occurs&quot; =&gt; 1,
              &quot;attributes =&gt; {
                   ... details of children as documented above
              },
              &quot;operations&quot; =&gt; {
                   .... details of operations as documented above
              },
              &quot;children&quot; =&gt; {
                   .... details of the children's children
              }
          }
     }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the recursive flag was false:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
     &quot;description&quot; =&gt; &quot;The connectors used to handle client connections&quot;,
     &quot;model-description&quot; =&gt; undefined
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="applying-updates-to-runtime-services"><a class="anchor" href="#applying-updates-to-runtime-services"></a><a class="link" href="#applying-updates-to-runtime-services">Applying Updates to Runtime Services</a></h5>
<div class="paragraph">
<p>An attribute or operation description may include a <code>restart-required</code>
descriptor; this section is an explanation of the
meaning of that descriptor.</p>
</div>
<div class="paragraph">
<p>An operation that changes a management resource&#8217;s persistent
configuration usually can also also affect a runtime service associated
with the resource. For example, there is a runtime service associated
with any host.xml or standalone.xml <code>&lt;interface&gt;</code> element; other
services in the runtime depend on that service to provide the
<code>InetAddress</code> associated with the interface. In many cases, an update to
a resource&#8217;s persistent configuration can be immediately applied to the
associated runtime service. The runtime service&#8217;s state is updated to
reflect the new value(s).</p>
</div>
<div class="paragraph">
<p>However, in many cases the runtime service&#8217;s state cannot be updated
without restarting the service. Restarting a service can have broad
effects. A restart of a service A will trigger a restart of other
services B, C and D that depend on A, triggering a restart of services that
depend on B, C and D, etc. Those service restarts may very well disrupt
handling of end-user requests.</p>
</div>
<div class="paragraph">
<p>Because restarting a service can be disruptive to end-user request
handling, the handlers for management operations will not restart any
service without some form of explicit instruction from the end user
indicating a service restart is desired. In a few cases, simply
executing the operation is an indication the user wants services to
restart (e.g. a <code>/host=primary/server-config=server-one:restart</code>
operation in a managed domain, or a <code>/:reload</code> operation on a standalone
server.) For all other cases, if an operation (or attribute write)
cannot be performed without restarting a service, the metadata
describing the operation or attribute will include a <code>restart-required</code>
descriptor whose value indicates what is necessary
for the operation to affect the runtime:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>no-services</code> – Applying the operation to the runtime does not require
the restart of any services. This value is the default if the
restart-required descriptor is not present.</p>
</li>
<li>
<p><code>all-services</code> – The operation can only immediately update the
persistent configuration; applying the operation to the runtime will
require a subsequent restart of all services in the affected VM.
Executing the operation will put the server into a <code>reload-required</code>
state. Until a restart of all services is performed the response to this
operation and to any subsequent operation will include a response header
<code>"process-state" &#8658; "reload-required"</code>. For a standalone server, a
restart of all services can be accomplished by executing the <code>reload</code>
CLI command. For a server in a managed domain, restarting all services
is done via a reload operation targeting the particular server (e.g.
<code>/host=primary/server=server-one:reload</code>).</p>
</li>
<li>
<p><code>jvm</code> --The operation can only immediately update the persistent
configuration; applying the operation to the runtime will require a full
process restart (i.e. stop the JVM and launch a new JVM). Executing the
operation will put the server into a <code>restart-required</code> state. Until
a restart is performed the response to this operation and to any
subsequent operation will include a response header
<code>"process-state" &#8658; "restart-required"</code>. For a standalone server, a full
process restart requires first stopping the server via OS-level
operations (Ctrl-C, kill) or via the <code>shutdown</code> CLI command, and then
starting the server again from the command line. For a server in a
managed domain, restarting a server requires executing the
<code>/host=&lt;host&gt;/server-config=&lt;server&gt;:restart</code> operation.</p>
</li>
<li>
<p><code>resource-services</code> – The operation can only immediately update the
persistent configuration; applying the operation to the runtime will
require a subsequent restart of some services associated with the
resource. If the operation includes the request header
<code>"allow-resource-service-restart" &#8658; true</code>, the handler for the
operation will go ahead and restart the runtime service. Otherwise
executing the operation will put the server into a <code>reload-required</code>
state. (See the discussion of <code>all-services</code> above for more on the
<code>reload-required</code> state.)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="Expression_Resolution"><a class="anchor" href="#Expression_Resolution"></a><a class="link" href="#Expression_Resolution">10.3.2. Expression Resolution</a></h4>
<div class="paragraph">
<p>When resolving an expression in the model the following locations are checked.
For this example we will use the expression <code>${my.example-expr}</code>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>First we check if there is a system property with the name
<code>my.example-expr</code>.
If there is, we use its value as the result of the resolution.
If not, we continue checking the next locations.</p>
</li>
<li>
<p>We convert the name <code>my.example-expr</code> to upper case, and replace all
non-alphanumeric characters with underscores, ending up with
<code>MY_EXAMPLE_EXPR</code>. We check if there is an environment variable with that
name. If there is, we use its value as the result of the resolution.
If not, we continue checking the next location.</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This step was introduced for WildFly 25, and has the scope to introduce some issues in special cases. Say you have an environment variable <code>COMMON_VAR_NAME=foo</code> already in use, and you use <code>${common-var-name:bar}</code> in the wildfly configuration. Prior to WildFly 25, the default value (i.e. <code>bar</code>) will be used. In WildFly 25 and later, the value from the environment variable (i.e. <code>foo</code>) will be used.
</td>
</tr>
</table>
</div>
<div class="ulist">
<ul>
<li>
<p>If (and only if) the original name starts with <code>env.</code> we trim the prefix
and look for an environment variable called what we are left with, with no
conversion performed (e.g. if the original name was <code>env.example</code>, we look for
an environment variable called <code>example</code>; if the original name was
<code>env.MY_EXAMPLE_EXPR</code>, we look for an environment variable called <code>MY_EXAMPLE_EXPR</code>).
If there is such an environmet variable, we use its value as the result of the resolution.</p>
</li>
<li>
<p>If none of the above checks yielded a result, the resolution failed. The
final step is to check if the expression provided a default. Our <code>${my.example-expr}</code>
example provided no default, so the expression could not be resolved. If
we had specified a default in the expression the default is returned (e.g. for
<code>${my.example-expr:hello}</code>, the value <code>hello</code> is returned).</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="The_HTTP_management_API"><a class="anchor" href="#The_HTTP_management_API"></a><a class="link" href="#The_HTTP_management_API">10.4. The HTTP management API</a></h3>
<div class="sect3">
<h4 id="introduction"><a class="anchor" href="#introduction"></a><a class="link" href="#introduction">10.4.1. Introduction</a></h4>
<div class="paragraph">
<p>The Management API in WildFly is accessible through multiple channels,
one of them being HTTP and JSON.</p>
</div>
<div class="paragraph">
<p>Even if you haven&#8217;t used a curl command line you might already have used
this channel since it is how the web console interact with the
Management API.</p>
</div>
<div class="paragraph">
<p>WildFly is distributed secured by default, the default security
mechanism is <em>username / password</em> based making use of <strong>HTTP Digest</strong> for
the authentication process.</p>
</div>
<div class="paragraph">
<p>Thus <strong>you need to create a user</strong> with the add-user.sh script.</p>
</div>
</div>
<div class="sect3">
<h4 id="interacting-with-the-model"><a class="anchor" href="#interacting-with-the-model"></a><a class="link" href="#interacting-with-the-model">10.4.2. Interacting with the model</a></h4>
<div class="paragraph">
<p>Since we must be authenticated , the client will have to support HTTP
Digest authentication.</p>
</div>
<div class="paragraph">
<p>For example this can be activated in <em>curl</em> using the <em>--digest</em> option.</p>
</div>
<div class="paragraph">
<p>The WildFly HTTP Management API adheres to the REST principles so the
GET operations must be idempotent.</p>
</div>
<div class="paragraph">
<p>This means that using a request with method <strong>GET</strong> can be used to read
the model but <strong>you won&#8217;t be able to change it</strong>.</p>
</div>
<div class="paragraph">
<p>You must use <strong>POST</strong> to change the model or read it. A <strong>POST</strong> request may
contain the operation either in DMR or in JSON format as its body.</p>
</div>
<div class="paragraph">
<p>You have to define the <strong>Content-Type=application/json</strong> header in the
request to specify that you are using some JSON.</p>
</div>
<div class="paragraph">
<p>If you want to submit DMR in the request body then the <strong>Content-Type</strong> or
the <strong>Accept</strong> header should be <strong>"application/dmr-encoded"</strong>.</p>
</div>
</div>
<div class="sect3">
<h4 id="get-for-reading"><a class="anchor" href="#get-for-reading"></a><a class="link" href="#get-for-reading">10.4.3. GET for Reading</a></h4>
<div class="paragraph">
<p>While you can do everything with <strong>POST</strong>, some operations can be called
through a 'classical' <strong>GET</strong> request.</p>
</div>
<div class="paragraph">
<p>These are the supported operations for a GET :</p>
</div>
<div class="ulist">
<ul>
<li>
<p>attribute : for a read-attribute operation</p>
</li>
<li>
<p>resource : for a read-resource operation</p>
</li>
<li>
<p>resource-description : for a read-resource-description operation</p>
</li>
<li>
<p>snapshots : for the list-snapshots operation</p>
</li>
<li>
<p>operation-description : for a read-operation-description operation</p>
</li>
<li>
<p>operation-names : for ad read-operation-names operation</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The URL format is the following one : <em><a href="http://server:9990/management/" class="bare">http://server:9990/management/</a></em>
<em>&lt;path_to_resource&gt;?operation=&lt;operation_name&gt;&amp;operation_parameter=&lt;value&gt;&#8230;&#8203;</em></p>
</div>
<div class="paragraph">
<p><em>path_to_resource</em> is the path to the wanted resource replacing all '='
with '/' : thus for example subsystem=undertow/server=default-server
becomes subsystem/undertow/server/default-server.</p>
</div>
<div class="paragraph">
<p>So to read the server-state :</p>
</div>
<div class="literalblock">
<div class="content">
<pre>http://localhost:9990/management?operation=attribute&amp;name=server-state&amp;json.pretty=1</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="lets-read-some-resource"><a class="anchor" href="#lets-read-some-resource"></a><a class="link" href="#lets-read-some-resource">10.4.4. Let&#8217;s read some resource</a></h4>
<div class="ulist">
<ul>
<li>
<p>This is simple operation that is equivalent of running
:read-attribute(name=server-state) with CLI in root directory</p>
<div class="ulist">
<ul>
<li>
<p>Using GET</p>
<div class="literalblock">
<div class="content">
<pre>http://localhost:9990/management?operation=attribute&amp;name=server-state&amp;json.pretty=1</pre>
</div>
</div>
</li>
<li>
<p>Using POST</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ curl --digest -L -D - http://localhost:9990/management --header &quot;Content-Type: application/json&quot; -d '{&quot;operation&quot;:&quot;read-attribute&quot;,&quot;name&quot;:&quot;server-state&quot;,&quot;json.pretty&quot;:1}' -u admin
Enter host password for user 'admin':
HTTP/1.1 401 Unauthorized
Connection: keep-alive
WWW-Authenticate: Digest realm=&quot;ManagementRealm&quot;,domain=&quot;/management&quot;,nonce=&quot;P80WU3BANtQNMTQwNjg5Mzc5MDQ2MlpjmRaZ+Vlp1OVeNEGBeXg=&quot;,opaque=&quot;00000000000000000000000000000000&quot;,algorithm=MD5
Content-Length: 77
Content-Type: text/html
Date: Fri, 01 Aug 2014 11:49:50 GMT

HTTP/1.1 200 OK
Connection: keep-alive
Authentication-Info: nextnonce=&quot;M+h9aADejeINMTQwNjg5Mzc5MDQ2OPQbHKdAS8pRE8BbGEDY5uI=&quot;
Content-Type: application/json; charset=utf-8
Content-Length: 55
Date: Fri, 01 Aug 2014 11:49:50 GMT

{
    &quot;outcome&quot; : &quot;success&quot;,
    &quot;result&quot; : &quot;running&quot;
}</code></pre>
</div>
</div>
</li>
</ul>
</div>
</li>
<li>
<p>Here&#8217;s an example of an operation on a resource with a nested address
and passed parameters. This is same as if you would run
<strong>/host=primary/server=server-01:read-attribute(name=server-state)</strong></p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ curl --digest -L -D - http://localhost:9990/management --header &quot;Content-Type: application/json&quot; -d '{&quot;operation&quot;:&quot;read-attribute&quot;,&quot;address&quot;:[{&quot;host&quot;:&quot;primary&quot;},{&quot;server&quot;:&quot;server-01&quot;}],&quot;name&quot;:&quot;server-state&quot;,&quot;json.pretty&quot;:1}'
HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: application/json
Date: Tue, 17 Apr 2012 04:02:24 GMT

{
 &quot;outcome&quot; : &quot;success&quot;,
 &quot;result&quot; : &quot;running&quot;
}</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Following example will get us information from http connection in
undertow subsystem including run-time attributes<br>
This is the same as running
/subsystem=undertow/server=default-server:read-resource(include-runtime=true,recursive=true)
in CLI</p>
<div class="ulist">
<ul>
<li>
<p>Using GET</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>http://localhost:9990/management/subsystem/undertow/server/default-server?operation=resource&amp;recursive=true&amp;json.pretty=1

{
    &quot;default-host&quot; : &quot;default-host&quot;,
    &quot;servlet-container&quot; : &quot;default&quot;,
    &quot;ajp-listener&quot; : null,
    &quot;host&quot; : {&quot;default-host&quot; : {
        &quot;alias&quot; : [&quot;localhost&quot;],
        &quot;default-web-module&quot; : &quot;ROOT.war&quot;,
        &quot;filter-ref&quot; : {
            &quot;server-header&quot; : {&quot;predicate&quot; : null},
            &quot;x-powered-by-header&quot; : {&quot;predicate&quot; : null}
        },
        &quot;location&quot; : {&quot;/&quot; : {
            &quot;handler&quot; : &quot;welcome-content&quot;,
            &quot;filter-ref&quot; : null
        }},
        &quot;setting&quot; : null
    }},
    &quot;http-listener&quot; : {&quot;default&quot; : {
        &quot;allow-encoded-slash&quot; : false,
        &quot;allow-equals-in-cookie-value&quot; : false,
        &quot;always-set-keep-alive&quot; : true,
        &quot;buffer-pipelined-data&quot; : true,
        &quot;buffer-pool&quot; : &quot;default&quot;,
        &quot;certificate-forwarding&quot; : false,
        &quot;decode-url&quot; : true,
        &quot;enabled&quot; : true,
        &quot;max-buffered-request-size&quot; : 16384,
        &quot;max-cookies&quot; : 200,
        &quot;max-header-size&quot; : 51200,
        &quot;max-headers&quot; : 200,
        &quot;max-parameters&quot; : 1000,
        &quot;max-post-size&quot; : 10485760,
        &quot;proxy-address-forwarding&quot; : false,
        &quot;read-timeout&quot; : null,
        &quot;receive-buffer&quot; : null,
        &quot;record-request-start-time&quot; : false,
        &quot;redirect-socket&quot; : &quot;https&quot;,
        &quot;send-buffer&quot; : null,
        &quot;socket-binding&quot; : &quot;http&quot;,
        &quot;tcp-backlog&quot; : null,
        &quot;tcp-keep-alive&quot; : null,
        &quot;url-charset&quot; : &quot;UTF-8&quot;,
        &quot;worker&quot; : &quot;default&quot;,
        &quot;write-timeout&quot; : null
    }},
    &quot;https-listener&quot; : null
}</code></pre>
</div>
</div>
</li>
<li>
<p>Using POST</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ curl --digest -D - http://localhost:9990/management --header &quot;Content-Type: application/json&quot; -d '{&quot;operation&quot;:&quot;read-resource&quot;, &quot;include-runtime&quot;:&quot;true&quot; , &quot;recursive&quot;:&quot;true&quot;, &quot;address&quot;:[&quot;subsystem&quot;,&quot;undertow&quot;,&quot;server&quot;,&quot;default-server&quot;], &quot;json.pretty&quot;:1}' -u admin:admin
HTTP/1.1 401 Unauthorized
Connection: keep-alive
WWW-Authenticate: Digest realm=&quot;ManagementRealm&quot;,domain=&quot;/management&quot;,nonce=&quot;a3paQ9E0/l8NMTQwNjg5OTU0NDk4OKjmim2lopZNc5zCevjYWpk=&quot;,opaque=&quot;00000000000000000000000000000000&quot;,algorithm=MD5
Content-Length: 77
Content-Type: text/html
Date: Fri, 01 Aug 2014 13:25:44 GMT

HTTP/1.1 200 OK
Connection: keep-alive
Authentication-Info: nextnonce=&quot;nTOSJd3ufO4NMTQwNjg5OTU0NDk5MeUsRw5rKXUT4Qvk1nbrG5c=&quot;
Content-Type: application/json; charset=utf-8
Content-Length: 1729
Date: Fri, 01 Aug 2014 13:25:45 GMT

{
    &quot;outcome&quot; : &quot;success&quot;,
    &quot;result&quot; : {
        &quot;default-host&quot; : &quot;default-host&quot;,
        &quot;servlet-container&quot; : &quot;default&quot;,
        &quot;ajp-listener&quot; : null,
        &quot;host&quot; : {&quot;default-host&quot; : {
            &quot;alias&quot; : [&quot;localhost&quot;],
            &quot;default-web-module&quot; : &quot;ROOT.war&quot;,
            &quot;filter-ref&quot; : {
                &quot;server-header&quot; : {&quot;predicate&quot; : null},
                &quot;x-powered-by-header&quot; : {&quot;predicate&quot; : null}
            },
            &quot;location&quot; : {&quot;/&quot; : {
                &quot;handler&quot; : &quot;welcome-content&quot;,
                &quot;filter-ref&quot; : null
            }},
            &quot;setting&quot; : null
        }},
        &quot;http-listener&quot; : {&quot;default&quot; : {
            &quot;allow-encoded-slash&quot; : false,
            &quot;allow-equals-in-cookie-value&quot; : false,
            &quot;always-set-keep-alive&quot; : true,
            &quot;buffer-pipelined-data&quot; : true,
            &quot;buffer-pool&quot; : &quot;default&quot;,
            &quot;certificate-forwarding&quot; : false,
            &quot;decode-url&quot; : true,
            &quot;enabled&quot; : true,
            &quot;max-buffered-request-size&quot; : 16384,
            &quot;max-cookies&quot; : 200,
            &quot;max-header-size&quot; : 51200,
            &quot;max-headers&quot; : 200,
            &quot;max-parameters&quot; : 1000,
            &quot;max-post-size&quot; : 10485760,
            &quot;proxy-address-forwarding&quot; : false,
            &quot;read-timeout&quot; : null,
            &quot;receive-buffer&quot; : null,
            &quot;record-request-start-time&quot; : false,
            &quot;redirect-socket&quot; : &quot;https&quot;,
            &quot;send-buffer&quot; : null,
            &quot;socket-binding&quot; : &quot;http&quot;,
            &quot;tcp-backlog&quot; : null,
            &quot;tcp-keep-alive&quot; : null,
            &quot;url-charset&quot; : &quot;UTF-8&quot;,
            &quot;worker&quot; : &quot;default&quot;,
            &quot;write-timeout&quot; : null
        }},
        &quot;https-listener&quot; : null
    }
}</code></pre>
</div>
</div>
</li>
</ul>
</div>
</li>
<li>
<p>You may also used some encoded DMR but the result won&#8217;t be human
readable</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>curl --digest -u admin:admin --header &quot;Content-Type: application/dmr-encoded&quot; -d bwAAAAMACW9wZXJhdGlvbnMADXJlYWQtcmVzb3VyY2UAB2FkZHJlc3NsAAAAAAAHcmVjdXJzZVoB  http://localhost:9990/management</code></pre>
</div>
</div>
</li>
<li>
<p>You can deploy applications on the server</p>
<div class="ulist">
<ul>
<li>
<p>First upload the file which will create a managed content. You will
have to use <a href="http://localhost:9990/management/" class="bare">http://localhost:9990/management/</a><strong>add-content</strong></p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>curl --digest -u admin:admin --form file=@tiny-webapp.war  http://localhost:9990/management/add-content
{&quot;outcome&quot; : &quot;success&quot;, &quot;result&quot; : { &quot;BYTES_VALUE&quot; : &quot;+QJlHTDrogO9pm/57GkT/vxWNz0=&quot; }}</code></pre>
</div>
</div>
</li>
<li>
<p>Now let&#8217;s deploy the application</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>curl --digest -u admin:admin -L --header &quot;Content-Type: application/json&quot; -d '{&quot;content&quot;:[{&quot;hash&quot;: {&quot;BYTES_VALUE&quot; : &quot;+QJlHTDrogO9pm/57GkT/vxWNz0=&quot;}}], &quot;address&quot;: [{&quot;deployment&quot;:&quot;tiny-webapp.war&quot;}], &quot;operation&quot;:&quot;add&quot;, &quot;enabled&quot;:&quot;true&quot;}' http://localhost:9990/management
{&quot;outcome&quot; : &quot;success&quot;}</code></pre>
</div>
</div>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="using-some-Jakarta-RESTful-Web-Services-code"><a class="anchor" href="#using-some-Jakarta-RESTful-Web-Services-code"></a><a class="link" href="#using-some-Jakarta-RESTful-Web-Services-code">10.4.5. Using some Jakarta RESTful Web Services code</a></h4>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">HttpAuthenticationFeature feature = HttpAuthenticationFeature.digest(<span class="string"><span class="delimiter">&quot;</span><span class="content">admin</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">admin</span><span class="delimiter">&quot;</span></span>);
Client client = ClientBuilder.newClient();
client.register(feature);
<span class="predefined-type">Entity</span>&lt;SimpleOperation&gt; operation = <span class="predefined-type">Entity</span>.entity(
    <span class="keyword">new</span> SimpleOperation(<span class="string"><span class="delimiter">&quot;</span><span class="content">read-resource</span><span class="delimiter">&quot;</span></span>, <span class="predefined-constant">true</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">subsystem</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">undertow</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">server</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">default-server</span><span class="delimiter">&quot;</span></span>),
    MediaType.APPLICATION_JSON_TYPE);
WebTarget managementResource = client.target(<span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:9990/management</span><span class="delimiter">&quot;</span></span>);
<span class="predefined-type">String</span> response = managementResource.request(MediaType.APPLICATION_JSON_TYPE)
    .header(<span class="string"><span class="delimiter">&quot;</span><span class="content">Content-type</span><span class="delimiter">&quot;</span></span>, MediaType.APPLICATION_JSON)
    .post(operation, <span class="predefined-type">String</span>.class);
<span class="predefined-type">System</span>.out.println(response);


{<span class="string"><span class="delimiter">&quot;</span><span class="content">outcome</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">success</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">servlet-container</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">ajp-listener</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">host</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">default-host</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">alias</span><span class="delimiter">&quot;</span></span> : [<span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span>], <span class="string"><span class="delimiter">&quot;</span><span class="content">default-web-module</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">ROOT.war</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">filter-ref</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">server-header</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">predicate</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}, <span class="string"><span class="delimiter">&quot;</span><span class="content">x-powered-by-header</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">predicate</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}}, <span class="string"><span class="delimiter">&quot;</span><span class="content">location</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">/</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">handler</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">welcome-content</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">filter-ref</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}}, <span class="string"><span class="delimiter">&quot;</span><span class="content">setting</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}}, <span class="string"><span class="delimiter">&quot;</span><span class="content">http-listener</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span> : {<span class="string"><span class="delimiter">&quot;</span><span class="content">allow-encoded-slash</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">false</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">allow-equals-in-cookie-value</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">false</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">always-set-keep-alive</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">true</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">buffer-pipelined-data</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">true</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">buffer-pool</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">certificate-forwarding</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">false</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">decode-url</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">true</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">enabled</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">true</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-buffered-request-size</span><span class="delimiter">&quot;</span></span> : <span class="integer">16384</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-cookies</span><span class="delimiter">&quot;</span></span> : <span class="integer">200</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-header-size</span><span class="delimiter">&quot;</span></span> : <span class="integer">51200</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-headers</span><span class="delimiter">&quot;</span></span> : <span class="integer">200</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-parameters</span><span class="delimiter">&quot;</span></span> : <span class="integer">1000</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">max-post-size</span><span class="delimiter">&quot;</span></span> : <span class="integer">10485760</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">proxy-address-forwarding</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">false</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">read-timeout</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">receive-buffer</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">record-request-start-time</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">false</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">redirect-socket</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">https</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">send-buffer</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">socket-binding</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">tcp-backlog</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">tcp-keep-alive</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">url-charset</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">UTF-8</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">worker</span><span class="delimiter">&quot;</span></span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">default</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">write-timeout</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}}, <span class="string"><span class="delimiter">&quot;</span><span class="content">https-listener</span><span class="delimiter">&quot;</span></span> : <span class="predefined-constant">null</span>}}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="The_native_management_API"><a class="anchor" href="#The_native_management_API"></a><a class="link" href="#The_native_management_API">10.5. The native management API</a></h3>
<div class="paragraph">
<p>A standalone WildFly process, or a managed domain Domain Controller or
secondary Host Controller process can be configured to listen for remote
management requests using its "native management interface":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;native-interface</span> <span class="attribute-name">interface</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">port</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">9999</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">sasl-authentication-factory</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">management-sasl-authentication</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>~(See standalone/configuration/standalone.xml or
domain/configuration/host.xml)~</p>
</div>
<div class="paragraph">
<p>The CLI tool that comes with the application server uses this interface,
and user can develop custom clients that use it as well. In this section
we&#8217;ll cover the basics on how to develop such a client. We&#8217;ll also cover
details on the format of low-level management operation requests and
responses – information that should prove useful for users of the CLI
tool as well.</p>
</div>
<div class="sect3">
<h4 id="native-management-client-dependencies"><a class="anchor" href="#native-management-client-dependencies"></a><a class="link" href="#native-management-client-dependencies">10.5.1. Native Management Client Dependencies</a></h4>
<div class="paragraph">
<p>The native management interface uses an open protocol based on the JBoss
Remoting library. JBoss Remoting is used to establish a communication
channel from the client to the process being managed. Once the
communication channel is established the primary traffic over the
channel is management requests initiated by the client and asynchronous
responses from the target process.</p>
</div>
<div class="paragraph">
<p>A custom Java-based client should have the maven artifact
<code>org.jboss.as:jboss-as-controller-client</code> and its dependencies on the
classpath. The other dependencies are:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Maven Artifact</th>
<th class="tableblock halign-left valign-top">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.remoting:jboss-remoting</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Remote communication</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss:jboss-dmr</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detyped representation of the management model</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.as:jboss-as-protocol</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Wire protocol for remote WildFly
management</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.sasl:jboss-sasl</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">SASL authentication</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.xnio:xnio-api</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Non-blocking IO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.xnio:xnio-nio</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Non-blocking IO</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.logging:jboss-logging</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Logging</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.threads:jboss-threads</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Thread management</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">org.jboss.marshalling:jboss-marshalling</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Marshalling and unmarshalling
data to/from streams</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The client API is entirely within the
<code>org.jboss.as:jboss-as-controller-client</code> artifact; the other
dependencies are part of the internal implementation of
<code>org.jboss.as:jboss-as-controller-client</code> and are not compile-time
dependencies of any custom client based on it.</p>
</div>
<div class="paragraph">
<p>The management protocol is an open protocol, so a completely custom
client could be developed without using these libraries (e.g. using
Python or some other language.)</p>
</div>
</div>
<div class="sect3">
<h4 id="working-with-a-modelcontrollerclient"><a class="anchor" href="#working-with-a-modelcontrollerclient"></a><a class="link" href="#working-with-a-modelcontrollerclient">10.5.2. Working with a ModelControllerClient</a></h4>
<div class="paragraph">
<p>The <code>org.jboss.as.controller.client.ModelControllerClient</code> class is the
main class a custom client would use to manage a WildFly server instance
or a Domain Controller or secondary Host Controller.</p>
</div>
<div class="paragraph">
<p>The custom client must have maven artifact
<code>org.jboss.as:jboss-as-controller-client</code> and its dependencies on the
classpath.</p>
</div>
<div class="sect4">
<h5 id="creating-the-modelcontrollerclient"><a class="anchor" href="#creating-the-modelcontrollerclient"></a><a class="link" href="#creating-the-modelcontrollerclient">Creating the ModelControllerClient</a></h5>
<div class="paragraph">
<p>To create a management client that can connect to your target process&#8217;s
native management socket, simply:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ModelControllerClient client = ModelControllerClient.Factory.create(InetAddress.getByName("localhost"), 9999);</pre>
</div>
</div>
<div class="paragraph">
<p>The address and port are what is configured in the target process'
<code>&lt;management&gt;&lt;management-interfaces&gt;&lt;native-interface&#8230;&#8203;/&gt;</code> element.</p>
</div>
<div class="paragraph">
<p>Typically, however, the native management interface will be secured,
requiring clients to authenticate. On the client side, the custom client
will need to provide the user&#8217;s authentication credentials, obtained in
whatever manner is appropriate for the client (e.g. from a dialog box in
a GUI-based client.) Access to these credentials is provided by passing
in an implementation of the
<code>javax.security.auth.callback.CallbackHandler</code> interface. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">static</span> ModelControllerClient createClient(<span class="directive">final</span> <span class="predefined-type">InetAddress</span> host, <span class="directive">final</span> <span class="type">int</span> port,
                  <span class="directive">final</span> <span class="predefined-type">String</span> username, <span class="directive">final</span> <span class="type">char</span><span class="type">[]</span> password, <span class="directive">final</span> <span class="predefined-type">String</span> securityRealmName) {
<span class="error"> </span>
    <span class="directive">final</span> <span class="predefined-type">CallbackHandler</span> callbackHandler = <span class="keyword">new</span> <span class="predefined-type">CallbackHandler</span>() {
<span class="error"> </span>
        <span class="directive">public</span> <span class="type">void</span> handle(<span class="predefined-type">Callback</span><span class="type">[]</span> callbacks) <span class="directive">throws</span> <span class="exception">IOException</span>, <span class="exception">UnsupportedCallbackException</span> {
            <span class="keyword">for</span> (<span class="predefined-type">Callback</span> current : callbacks) {
                <span class="keyword">if</span> (current <span class="keyword">instanceof</span> <span class="predefined-type">NameCallback</span>) {
                    <span class="predefined-type">NameCallback</span> ncb = (<span class="predefined-type">NameCallback</span>) current;
                    ncb.setName(username);
                } <span class="keyword">else</span> <span class="keyword">if</span> (current <span class="keyword">instanceof</span> <span class="predefined-type">PasswordCallback</span>) {
                    <span class="predefined-type">PasswordCallback</span> pcb = (<span class="predefined-type">PasswordCallback</span>) current;
                    pcb.setPassword(password.toCharArray());
                } <span class="keyword">else</span> <span class="keyword">if</span> (current <span class="keyword">instanceof</span> <span class="predefined-type">RealmCallback</span>) {
                    <span class="predefined-type">RealmCallback</span> rcb = (<span class="predefined-type">RealmCallback</span>) current;
                    rcb.setText(rcb.getDefaultText());
                } <span class="keyword">else</span> {
                    <span class="keyword">throw</span> <span class="keyword">new</span> <span class="exception">UnsupportedCallbackException</span>(current);
                }
            }
        }
    };
<span class="error"> </span>
    <span class="keyword">return</span> ModelControllerClient.Factory.create(host, port, callbackHandler);
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="creating-an-operation-request-object"><a class="anchor" href="#creating-an-operation-request-object"></a><a class="link" href="#creating-an-operation-request-object">Creating an operation request object</a></h5>
<div class="paragraph">
<p>Management requests are formulated using the <code>org.jboss.dmr.ModelNode</code>
class from the <code>jboss-dmr</code> library. The <code>jboss-dmr</code> library allows the
complete WildFly management model to be expressed using a very small
number of Java types. See
<a href="#Detyped_management_and_the_jboss-dmr_library">Detyped
management and the jboss-dmr library</a> for full details on using this
library.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s show an example of creating an operation request object that can
be used to
<a href="Global_operations.html#src-557234_Globaloperations-read-resource-description">read
the resource description</a> for the web subsystem&#8217;s HTTP connector:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode op = <span class="keyword">new</span> ModelNode();
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">operation</span><span class="delimiter">&quot;</span></span>).set(<span class="string"><span class="delimiter">&quot;</span><span class="content">read-resource-description</span><span class="delimiter">&quot;</span></span>);
<span class="error"> </span>
ModelNode address = op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">address</span><span class="delimiter">&quot;</span></span>);
address.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">subsystem</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">web</span><span class="delimiter">&quot;</span></span>);
address.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">connector</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>);
<span class="error"> </span>
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">recursive</span><span class="delimiter">&quot;</span></span>).set(<span class="predefined-constant">true</span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">operations</span><span class="delimiter">&quot;</span></span>).set(<span class="predefined-constant">true</span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>What we&#8217;ve done here is created a ModelNode of type <code>ModelType.OBJECT</code>
with the following fields:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>operation</code> – the name of the operation to invoke. All operation
requests <strong>must</strong> include this field and its value must be a String.</p>
</li>
<li>
<p><code>address</code> – the address of the resource to invoke the operation
against. This field&#8217;s must be of <code>ModelType.LIST</code> with each element in
the list being a <code>ModelType.PROPERTY</code>. If this field is omitted the
operation will target the root resource. The operation can be targeted
at any address in the management model; here we are targeting it at the
resource for the web subsystem&#8217;s http connector.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In this case, the request includes two optional parameters:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>recursive</code> – true means you want the description of child resources
under this resource. Default is false</p>
</li>
<li>
<p><code>operations</code> – true means you want the description of operations
exposed by the resource to be included. Default is false.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Different operations take different parameters, and some take no
parameters at all.</p>
</div>
<div class="paragraph">
<p>See <a href="#format-of-a-detyped-operation-request">Format of a
Detyped Operation Request</a> for full details on the structure of a
ModelNode that will represent an operation request.</p>
</div>
<div class="paragraph">
<p>The example above produces an operation request ModelNode equivalent to
what the CLI produces internally when it parses and executes the
following low-level CLI command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[localhost:9999 /] /subsystem=web/connector=http:read-resource-description(recursive=true,operations=true)</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="execute-the-operation-and-manipulate-the-result"><a class="anchor" href="#execute-the-operation-and-manipulate-the-result"></a><a class="link" href="#execute-the-operation-and-manipulate-the-result">Execute the operation and manipulate the result:</a></h5>
<div class="paragraph">
<p>The <code>execute</code> method sends the operation request ModelNode to the
process being managed and returns a ModelNode the contains the process'
response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode returnVal = client.execute(op);
<span class="predefined-type">System</span>.out.println(returnVal.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span>).toString());</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#format-of-a-detyped-operation-response">Format of a
Detyped Operation Response</a> for general details on the structure of the
"returnVal" ModelNode.</p>
</div>
<div class="paragraph">
<p>The <code>execute</code> operation shown above will block the calling thread until
the response is received from the process being managed.
<code>ModelControllerClient</code> also exposes and API allowing asynchronous
invocation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="predefined-type">Future</span>&lt;ModelNode&gt; future = client.executeAsync(op);
. . .  <span class="comment">// do other stuff</span>
ModelNode returnVal = future.get();
<span class="predefined-type">System</span>.out.println(returnVal.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">result</span><span class="delimiter">&quot;</span></span>).toString());</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="close-the-modelcontrollerclient"><a class="anchor" href="#close-the-modelcontrollerclient"></a><a class="link" href="#close-the-modelcontrollerclient">Close the ModelControllerClient</a></h5>
<div class="paragraph">
<p>A <code>ModelControllerClient</code> can be reused for multiple requests. Creating
a new <code>ModelControllerClient</code> for each request is an anti-pattern.
However, when the <code>ModelControllerClient</code> is no longer needed, it should
always be explicitly closed, allowing it to close down any connections
to the process it was managing and release other resources:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">client.close();</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="format-of-a-detyped-operation-request"><a class="anchor" href="#format-of-a-detyped-operation-request"></a><a class="link" href="#format-of-a-detyped-operation-request">10.5.3. Format of a Detyped Operation Request</a></h4>
<div class="paragraph">
<p>The basic method a user of the WildFly 27 programmatic management API
would use is very simple:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode execute(ModelNode operation) <span class="directive">throws</span> <span class="exception">IOException</span>;</code></pre>
</div>
</div>
<div class="paragraph">
<p>where the return value is the detyped representation of the response,
and <code>operation</code> is the detyped representation of the operation being
invoked.</p>
</div>
<div class="paragraph">
<p>The purpose of this section is to document the structure of <code>operation</code>.</p>
</div>
<div class="paragraph">
<p>See <a href="#format-of-a-detyped-operation-response">Format of a
Detyped Operation Response</a> for a discussion of the format of the
response.</p>
</div>
<div class="sect4">
<h5 id="simple-operations"><a class="anchor" href="#simple-operations"></a><a class="link" href="#simple-operations">Simple Operations</a></h5>
<div class="paragraph">
<p>A text representation of simple operation would look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;operation&quot; =&gt; &quot;write-attribute&quot;,
    &quot;address&quot; =&gt; [
        (&quot;profile&quot; =&gt; &quot;production&quot;),
        (&quot;subsystem&quot; =&gt; &quot;threads&quot;),
        (&quot;bounded-queue-thread-pool&quot; =&gt; &quot;pool1&quot;)
    ],
    &quot;name&quot; =&gt; &quot;count&quot;,
    &quot;value&quot; =&gt; 20
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Java code to produce that output would be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode op = <span class="keyword">new</span> ModelNode();
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">operation</span><span class="delimiter">&quot;</span></span>).set(<span class="string"><span class="delimiter">&quot;</span><span class="content">write-attribute</span><span class="delimiter">&quot;</span></span>);
ModelNode addr = op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">address</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">profile</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">production</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">subsystem</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">threads</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">bounded-queue-thread-pool</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">pool1</span><span class="delimiter">&quot;</span></span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>).set(<span class="string"><span class="delimiter">&quot;</span><span class="content">count</span><span class="delimiter">&quot;</span></span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">value</span><span class="delimiter">&quot;</span></span>).set(<span class="integer">20</span>);
<span class="predefined-type">System</span>.out.println(op);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The order in which the outermost elements appear in the request is not
relevant. The required elements are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>operation</code> – String – The name of the operation being invoked.</p>
</li>
<li>
<p><code>address</code> – the address of the managed resource against which the
request should be executed. If not set, the address is the root
resource. The address is an ordered list of key-value pairs describing
where the resource resides in the overall management resource tree.
Management resources are organized in a tree, so the order in which
elements in the address occur is important.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The other key/value pairs are parameter names and their values. The
names and values should match what is specified in the
<a href="Description_of_the_Management_Model.html#src-557210_DescriptionoftheManagementModel-operation-description">operation&#8217;s
description</a>.</p>
</div>
<div class="paragraph">
<p>Parameters may have any name, except for the reserved words <code>operation</code>,
<code>address</code> and <code>operation-headers</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="operation-headers"><a class="anchor" href="#operation-headers"></a><a class="link" href="#operation-headers">Operation Headers</a></h5>
<div class="paragraph">
<p>Besides the special operation and address values discussed above,
operation requests can also include special "header" values that help
control how the operation executes. These headers are created under the
special reserved word <code>operation-headers</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode op = <span class="keyword">new</span> ModelNode();
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">operation</span><span class="delimiter">&quot;</span></span>).set(<span class="string"><span class="delimiter">&quot;</span><span class="content">write-attribute</span><span class="delimiter">&quot;</span></span>);
ModelNode addr = op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">address</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">base</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">profile</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">production</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">subsystem</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">threads</span><span class="delimiter">&quot;</span></span>);
addr.add(<span class="string"><span class="delimiter">&quot;</span><span class="content">bounded-queue-thread-pool</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">pool1</span><span class="delimiter">&quot;</span></span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>).set(<span class="string"><span class="delimiter">&quot;</span><span class="content">count</span><span class="delimiter">&quot;</span></span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">value</span><span class="delimiter">&quot;</span></span>).set(<span class="integer">20</span>);
op.get(<span class="string"><span class="delimiter">&quot;</span><span class="content">operation-headers</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">rollback-on-runtime-failure</span><span class="delimiter">&quot;</span></span>).set(<span class="predefined-constant">false</span>);
<span class="predefined-type">System</span>.out.println(op);</code></pre>
</div>
</div>
<div class="paragraph">
<p>This produces:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;operation&quot; =&gt; &quot;write-attribute&quot;,
    &quot;address&quot; =&gt; [
        (&quot;profile&quot; =&gt; &quot;production&quot;),
        (&quot;subsystem&quot; =&gt; &quot;threads&quot;),
        (&quot;bounded-queue-thread-pool&quot; =&gt; &quot;pool1&quot;)
    ],
    &quot;name&quot; =&gt; &quot;count&quot;,
    &quot;value&quot; =&gt; 20,
    &quot;operation-headers&quot; =&gt; {
        &quot;rollback-on-runtime-failure =&gt; false
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following operation headers are supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>rollback-on-runtime-failure</code> – boolean, optional, defaults to true.
Whether an operation that successfully updates the persistent
configuration model should be reverted if it fails to apply to the
runtime. Operations that affect the persistent configuration are applied
in two stages – first to the configuration model and then to the actual
running services. If there is an error applying to the configuration
model the operation will be aborted with no configuration change and no
change to running services will be attempted. However, operations are
allowed to change the configuration model even if there is a failure to
apply the change to the running services – if and only if this
<code>rollback-on-runtime-failure</code> header is set to <code>false</code>. So, this header
only deals with what happens if there is a problem applying an operation
to the running state of a server (e.g. actually increasing the size of a
runtime thread pool.)</p>
</li>
<li>
<p><code>rollout-plan</code> – only relevant to requests made to a Domain Controller
or Host Controller. See "
<a href="#operations-with-a-rollout-plan">Operations with a
Rollout Plan</a>" for details.</p>
</li>
<li>
<p><code>allow-resource-service-restart</code> – boolean, optional, defaults to
false. Whether an operation that requires restarting some runtime
services in order to take effect should do so. See discussion of
<code>resource-services</code> in the
<a href="Description_of_the_Management_Model.html#src-557210_DescriptionoftheManagementModel-applying-runtime-updates">"Applying
Updates to Runtime Services" section of the Description of the
Management Model section</a> for further details.</p>
</li>
<li>
<p><code>roles</code> – String or list of strings. Name(s) of RBAC role(s) the
permissions for which should be used when making access control
decisions instead of those from the roles normally associated with the
user invoking the operation. Only respected if the user is normally
associated with a role with all permissions (i.e. SuperUser), meaning
this can only be used to reduce permissions for a caller, not to
increase permissions.</p>
</li>
<li>
<p><code>blocking-timeout</code> – int, optional, defaults to 300. Maximum time, in
seconds, that the operation should block at various points waiting for
completion. If this period is exceeded, the operation will roll back.
Does not represent an overall maximum execution time for an operation;
rather it is meant to serve as a sort of fail-safe measure to prevent
problematic operations indefinitely tying up resources.</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="composite-operations"><a class="anchor" href="#composite-operations"></a><a class="link" href="#composite-operations">Composite Operations</a></h5>
<div class="paragraph">
<p>The root resource for a Domain or Host Controller or an individual
server will expose an operation named " `composite`". This operation
executes a list of other operations as an atomic unit (although the
atomicity requirement can be
<a href="#composite-operations">relaxed</a>.
The structure of the request for the " `composite`" operation has the
same fundamental structure as a simple operation (i.e. operation name,
address, params as key value pairs).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;operation&quot; =&gt; &quot;composite&quot;,
    &quot;address&quot; =&gt; [],
    &quot;steps&quot; =&gt; [
         {
              &quot;operation&quot; =&gt; &quot;write-attribute&quot;,
              &quot;address&quot; =&gt; [
                   (&quot;profile&quot; =&gt; &quot;production&quot;),
                   (&quot;subsystem&quot; =&gt; &quot;threads&quot;),
                   (&quot;bounded-queue-thread-pool&quot; =&gt; &quot;pool1&quot;)
              ],
              &quot;count&quot; =&gt; &quot;count&quot;,
              &quot;value&quot; =&gt; 20
         },
         {
              &quot;operation&quot; =&gt; &quot;write-attribute&quot;,
              &quot;address&quot; =&gt; [
                   (&quot;profile&quot; =&gt; &quot;production&quot;),
                   (&quot;subsystem&quot; =&gt; &quot;threads&quot;),
                   (&quot;bounded-queue-thread-pool&quot; =&gt; &quot;pool2&quot;)
              ],
              &quot;name&quot; =&gt; &quot;count&quot;,
              &quot;value&quot; =&gt; 10
         }
    ],
    &quot;operation-headers&quot; =&gt; {
        &quot;rollback-on-runtime-failure =&gt; false
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The "composite" operation takes a single parameter:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>steps</code> – a list, where each item in the list has the same structure
as a simple operation request. In the example above each of the two
steps is modifying the thread pool configuration for a different pool.
There need not be any particular relationship between the steps. Note
that the <code>rollback-on-runtime-failure</code> and <code>rollout-plan</code> operation
headers are not supported for the individual steps in a composite
operation.</p>
<div class="literalblock">
<div class="content">
<pre> +
The `rollback-on-runtime-failure` operation header discussed above has a
particular meaning when applied to a composite operation, controlling
whether steps that successfully execute should be reverted if other
steps fail at runtime. Note that if any steps modify the persistent
configuration, and any of those steps fail, all steps will be reverted.
Partial/incomplete changes to the persistent configuration are not
allowed.</pre>
</div>
</div>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="operations-with-a-rollout-plan"><a class="anchor" href="#operations-with-a-rollout-plan"></a><a class="link" href="#operations-with-a-rollout-plan">Operations with a Rollout Plan</a></h5>
<div class="paragraph">
<p>Operations targeted at domain or host level resources can potentially
impact multiple servers. Such operations can include a "rollout plan"
detailing the sequence in which the operation should be applied to
servers as well as policies for detailing whether the operation should
be reverted if it fails to execute successfully on some servers.</p>
</div>
<div class="paragraph">
<p>If the operation includes a rollout plan, the structure is as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;operation&quot; =&gt; &quot;write-attribute&quot;,
    &quot;address&quot; =&gt; [
        (&quot;profile&quot; =&gt; &quot;production&quot;),
        (&quot;subsystem&quot; =&gt; &quot;threads&quot;),
        (&quot;bounded-queue-thread-pool&quot; =&gt; &quot;pool1&quot;)
    ],
    &quot;name&quot; =&gt; &quot;count&quot;,
    &quot;value&quot; =&gt; 20,
    &quot;operation-headers&quot; =&gt; {
        &quot;rollout-plan&quot; =&gt; {
            &quot;in-series&quot; =&gt; [
                {
                    &quot;concurrent-groups&quot; =&gt; {
                        &quot;groupA&quot; =&gt; {
                            &quot;rolling-to-servers&quot; =&gt; true,
                            &quot;max-failure-percentage&quot; =&gt; 20
                        },
                        &quot;groupB&quot; =&gt; undefined
                    }
                },
                {
                   &quot;server-group&quot; =&gt; {
                        &quot;groupC&quot; =&gt; {
                            &quot;rolling-to-servers&quot; =&gt; false,
                            &quot;max-failed-servers&quot; =&gt; 1
                        }
                    }
                },
                {
                    &quot;concurrent-groups&quot; =&gt; {
                        &quot;groupD&quot; =&gt; {
                            &quot;rolling-to-servers&quot; =&gt; true,
                            &quot;max-failure-percentage&quot; =&gt; 20
                        },
                        &quot;groupE&quot; =&gt; undefined
                    }
                }
            ],
            &quot;rollback-across-groups&quot; =&gt; true
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, the rollout plan is another structure in the
operation-headers section. The root node of the structure allows two
children:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>in-series</code> – a list – A list of activities that are to be performed
in series, with each activity reaching completion before the next step
is executed. Each activity involves the application of the operation to
the servers in one or more server groups. See below for details on each
element in the list.</p>
</li>
<li>
<p><code>rollback-across-groups</code> – boolean – indicates whether the need to
rollback the operation on all the servers in one server group should
trigger a rollback across all the server groups. This is an optional
setting, and defaults to <code>false</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Each element in the list under the <code>in-series</code> node must have one or the
other of the following structures:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>concurrent-groups</code> – a map of server group names to policies
controlling how the operation should be applied to that server group.
For each server group in the map, the operation may be applied
concurrently. See below for details on the per-server-group policy
configuration.</p>
</li>
<li>
<p><code>server-group</code> – a single key/value mapping of a server group name to
a policy controlling how the operation should be applied to that server
group. See below for details on the policy configuration. (Note: there
is no difference in plan execution between this and a "
`concurrent-groups`" map with a single entry.)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The policy controlling how the operation is applied to the servers
within a server group has the following elements, each of which is
optional:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>rolling-to-servers</code> – boolean – If true, the operation will be
applied to each server in the group in series. If false or not
specified, the operation will be applied to the servers in the group
concurrently.</p>
</li>
<li>
<p><code>max-failed-servers</code> – int – Maximum number of servers in the group
that can fail to apply the operation before it should be reverted on all
servers in the group. The default value if not specified is zero; i.e.
failure on any server triggers rollback across the group.</p>
</li>
<li>
<p><code>max-failure-percentage</code> – int between 0 and 100 – Maximum percentage
of the total number of servers in the group that can fail to apply the
operation before it should be reverted on all servers in the group. The
default value if not specified is zero; i.e. failure on any server
triggers rollback across the group.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If both <code>max-failed-servers</code> and <code>max-failure-percentage</code> are set,
<code>max-failure-percentage</code> takes precedence.</p>
</div>
<div class="paragraph">
<p>Looking at the (contrived) example above, application of the operation
to the servers in the domain would be done in 3 phases. If the policy
for any server group triggers a rollback of the operation across the
server group, all other server groups will be rolled back as well. The 3
phases are:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Server groups groupA and groupB will have the operation applied
concurrently. The operation will be applied to the servers in groupA in
series, while all servers in groupB will handle the operation
concurrently. If more than 20% of the servers in groupA fail to apply
the operation, it will be rolled back across that group. If any servers
in groupB fail to apply the operation it will be rolled back across that
group.</p>
</li>
<li>
<p>Once all servers in groupA and groupB are complete, the operation
will be applied to the servers in groupC. Those servers will handle the
operation concurrently. If more than one server in groupC fails to apply
the operation it will be rolled back across that group.</p>
</li>
<li>
<p>Once all servers in groupC are complete, server groups groupD and
groupE will have the operation applied concurrently. The operation will
be applied to the servers in groupD in series, while all servers in
groupE will handle the operation concurrently. If more than 20% of the
servers in groupD fail to apply the operation, it will be rolled back
across that group. If any servers in groupE fail to apply the operation
it will be rolled back across that group.</p>
</li>
</ol>
</div>
<div class="sect5">
<h6 id="default-rollout-plan"><a class="anchor" href="#default-rollout-plan"></a><a class="link" href="#default-rollout-plan">Default Rollout Plan</a></h6>
<div class="paragraph">
<p>All operations that impact multiple servers will be executed with a
rollout plan. However, actually specifying the rollout plan in the
operation request is not required. If no <code>rollout-plan</code> operation header
is specified, a default plan will be generated. The plan will have the
following characteristics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>There will only be a single high level phase. All server groups
affected by the operation will have the operation applied concurrently.</p>
</li>
<li>
<p>Within each server group, the operation will be applied to all servers
concurrently.</p>
</li>
<li>
<p>Failure on any server in a server group will cause rollback across the
group.</p>
</li>
<li>
<p>Failure of any server group will result in rollback of all other
server groups.</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6 id="creating-and-reusing-a-rollout-plan"><a class="anchor" href="#creating-and-reusing-a-rollout-plan"></a><a class="link" href="#creating-and-reusing-a-rollout-plan">Creating and reusing a Rollout Plan</a></h6>
<div class="paragraph">
<p>Since a rollout plan may be quite complex, having to pass it as a header
every time can become quickly painful. So instead we can store it in the
model and then reference it when we want to use it.<br>
To create a rollout plan you can use the operation <code>rollout-plan add</code>
like this :</p>
</div>
<div class="listingblock">
<div class="content">
<pre>rollout-plan add --name=simple --content={"rollout-plan" =&gt; {"in-series" =&gt; [{"server-group" =&gt; {"main-server-group" =&gt; {"rolling-to-servers" =&gt; false,"max-failed-servers" =&gt; 1}}}, {"server-group" =&gt; {"other-server-group" =&gt; {"rolling-to-servers" =&gt; true,"max-failure-percentage" =&gt; 20}}}],"rollback-across-groups" =&gt; true}}</pre>
</div>
</div>
<div class="paragraph">
<p>This will create a rollout plan called <code>simple</code> in the content
repository.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@192.168.1.20:9999 /] /management-client-content=rollout-plans/rollout-plan=simple:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;content&quot; =&gt; {&quot;rollout-plan&quot; =&gt; {
            &quot;in-series&quot; =&gt; [
                {&quot;server-group&quot; =&gt; {&quot;main-server-group&quot; =&gt; {
                    &quot;rolling-to-servers&quot; =&gt; false,
                    &quot;max-failed-servers&quot; =&gt; 1
                }}},
                {&quot;server-group&quot; =&gt; {&quot;other-server-group&quot; =&gt; {
                    &quot;rolling-to-servers&quot; =&gt; true,
                    &quot;max-failure-percentage&quot; =&gt; 20
                }}}
            ],
            &quot;rollback-across-groups&quot; =&gt; true
        }},
        &quot;hash&quot; =&gt; bytes {
            0x13, 0x12, 0x76, 0x65, 0x8a, 0x28, 0xb8, 0xbc,
            0x34, 0x3c, 0xe9, 0xe6, 0x9f, 0x24, 0x05, 0xd2,
            0x30, 0xff, 0xa4, 0x34
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you may reference the roolout plan in your command by adding a
header just like this :</p>
</div>
<div class="listingblock">
<div class="content">
<pre>deploy /quickstart/ejb-in-war/target/wildfly-ejb-in-war.war --all-server-groups --headers={rollout name=simple}</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="format-of-a-detyped-operation-response"><a class="anchor" href="#format-of-a-detyped-operation-response"></a><a class="link" href="#format-of-a-detyped-operation-response">10.5.4. Format of a Detyped Operation Response</a></h4>
<div class="paragraph">
<p>As noted previously, the basic method a user of the WildFly 27
programmatic management API would use is very simple:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">ModelNode execute(ModelNode operation) <span class="directive">throws</span> <span class="exception">IOException</span>;</code></pre>
</div>
</div>
<div class="paragraph">
<p>where the return value is the detyped representation of the response,
and <code>operation</code> is the detyped representation of the operating being
invoked.</p>
</div>
<div class="paragraph">
<p>The purpose of this section is to document the structure of the return
value.</p>
</div>
<div class="paragraph">
<p>For the format of the request, see
<a href="#format-of-a-detyped-operation-request">Format of a
Detyped Operation Request</a>.</p>
</div>
<div class="sect4">
<h5 id="simple-responses"><a class="anchor" href="#simple-responses"></a><a class="link" href="#simple-responses">Simple Responses</a></h5>
<div class="paragraph">
<p>Simple responses are provided by the following types of operations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Non-composite operations that target a single server. (See below for
more on composite operations).</p>
</li>
<li>
<p>Non-composite operations that target a Domain Controller or secondary Host
Controller and don&#8217;t require the responder to apply the operation on
multiple servers and aggregate their results (e.g. a simple read of a
domain configuration property.)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The response will always include a simple boolean outcome field, with
one of three possible values:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>success</code> – the operation executed successfully</p>
</li>
<li>
<p><code>failed</code> – the operation failed</p>
</li>
<li>
<p><code>cancelled</code> – the execution of the operation was cancelled. (This
would be an unusual outcome for a simple operation which would generally
very rapidly reach a point in its execution where it couldn&#8217;t be
cancelled.)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The other fields in the response will depend on whether the operation
was successful.</p>
</div>
<div class="paragraph">
<p>The response for a failed operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;[JBAS-12345] Some failure message&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A response for a successful operation will include an additional field:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>result</code> – the return value, or <code>undefined</code> for void operations or
those that return null</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A non-void result:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;name&quot; =&gt; &quot;Brian&quot;,
        &quot;age&quot; =&gt; 22
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A void result:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The response for a cancelled operation has no other fields:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;cancelled&quot;
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="response-headers"><a class="anchor" href="#response-headers"></a><a class="link" href="#response-headers">Response Headers</a></h5>
<div class="paragraph">
<p>Besides the standard <code>outcome</code>, <code>result</code> and <code>failure-description</code>
fields described above, the response may also include various headers
that provide more information about the affect of the operation or about
the overall state of the server. The headers will be child element under
a field named <code>response-headers</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;response-headers&quot; =&gt; {
        &quot;operation-requires-reload&quot; =&gt; true,
        &quot;process-state&quot; =&gt; &quot;reload-required&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A response header is typically related to whether an operation could be
applied to the targeted runtime without requiring a restart of some or
all services, or even of the target process itself. Please see the
<a href="Description_of_the_Management_Model.html#src-557210_DescriptionoftheManagementModel-applying-runtime-updates">"Applying
Updates to Runtime Services" section of the Description of the
Management Model section</a> for a discussion of the basic concepts related
to what happens if an operation requires a service restart to be
applied.</p>
</div>
<div class="paragraph">
<p>The current possible response headers are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>operation-requires-reload</code> – boolean – indicates that the specific
operation that has generated this response requires a restart of all
services in the process in order to take effect in the runtime. This
would typically only have a value of 'true'; the absence of the header
is the same as a value of 'false.'</p>
</li>
<li>
<p><code>operation-requires-restart</code> – boolean – indicates that the specific
operation that has generated this response requires a full process
restart in order to take effect in the runtime. This would typically
only have a value of 'true'; the absence of the header is the same as a
value of 'false.'</p>
</li>
<li>
<p><code>process-state</code> – enumeration – Provides information about the overall
state of the target process. One of the following values:</p>
<div class="ulist">
<ul>
<li>
<p><code>starting</code> – the process is starting</p>
</li>
<li>
<p><code>running</code> – the process is in a normal running state. The
<code>process-state</code> header would typically not be seen with this value; the
absence of the header is the same as a value of 'running'.</p>
</li>
<li>
<p><code>reload-required</code> – some operation (not necessarily this one) has
executed that requires a restart of all services in order for a
configuration change to take effect in the runtime.</p>
</li>
<li>
<p><code>restart-required</code> – some operation (not necessarily this one) has
executed that requires a full process restart in order for a
configuration change to take effect in the runtime.</p>
</li>
<li>
<p><code>stopping</code> – the process is stopping</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="basic-composite-operation-responses"><a class="anchor" href="#basic-composite-operation-responses"></a><a class="link" href="#basic-composite-operation-responses">Basic Composite Operation Responses</a></h5>
<div class="paragraph">
<p>A composite operation is one that incorporates more than one simple
operation in a list and executes them atomically. See the
<a href="#composite-operations">"Composite
Operations" section</a> for more information.</p>
</div>
<div class="paragraph">
<p>Basic composite responses are provided by the following types of
operations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Composite operations that target a single server.</p>
</li>
<li>
<p>Composite operations that target a Domain Controller or a secondary Host
Controller and don&#8217;t require the responder to apply the operation on
multiple servers and aggregate their results (e.g. a list of simple
reads of domain configuration properties.)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The high level format of a basic composite operation response is largely
the same as that of a simple operation response, although there is an
important semantic difference. For a composite operation, the meaning of
the outcome flag is controlled by the value of the operation request&#8217;s
<code>rollback-on-runtime-failure</code> header field. If that field was <code>false</code>
(default is true), the outcome flag will be success if all steps were
successfully applied to the persistent configuration even if <strong>none</strong> of
the composite operation&#8217;s steps was successfully applied to the runtime.</p>
</div>
<div class="paragraph">
<p>What&#8217;s distinctive about a composite operation response is the <code>result</code>
field. First, even if the operation was not successful, the <code>result</code>
field will usually be present. (It won&#8217;t be present if there was some
sort of immediate failure that prevented the responder from even
attempting to execute the individual operations.) Second, the content of
the <code>result</code> field will be a map. Each entry in the map will record the
result of an element in the <code>steps</code> parameter of the composite operation
request. The key for each item in the map will be the string " <code>step-X`"
where "X" is the 1-based index of the step&#8217;s position in the request&#8217;s
`steps</code> list. So each individual operation in the composite operation
will have its result recorded.</p>
</div>
<div class="paragraph">
<p>The individual operation results will have the same basic format as the
simple operation results described above. However, there are some
differences from the simple operation case when the individual
operation&#8217;s <code>outcome</code> flag is <code>failed</code>. These relate to the fact that in
a composite operation, individual operations can be rolled back or not
even attempted.</p>
</div>
<div class="paragraph">
<p>If an individual operation was not even attempted (because the overall
operation was cancelled or, more likely, a prior operation failed):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;cancelled&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An individual operation that failed and was rolled back:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;[JBAS-12345] Some failure message&quot;,
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An individual operation that itself succeeded but was rolled back due to
failure of another operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;result&quot; =&gt; {
        &quot;name&quot; =&gt; &quot;Brian&quot;,
        &quot;age&quot; =&gt; 22
    },
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An operation that failed and was rolled back:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;[JBAS-12345] Some failure message&quot;,
    &quot;rolled-back&quot; =&gt; true
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here&#8217;s an example of the response for a successful 2 step composite
operation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        {
            &quot;outcome&quot; =&gt; &quot;success&quot;,
            &quot;result&quot; =&gt; {
                &quot;name&quot; =&gt; &quot;Brian&quot;,
                &quot;age&quot; =&gt; 22
            }
        },
        {
            &quot;outcome&quot; =&gt; &quot;success&quot;,
            &quot;result&quot; =&gt; undefined
        }
    ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>And for a failed 3 step composite operation, where the first step
succeeded and the second failed, triggering cancellation of the 3rd and
rollback of the others:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; &quot;[JBAS-99999] Composite operation failed; see individual operation results for details&quot;,
    &quot;result&quot; =&gt; [
        {
            &quot;outcome&quot; =&gt; &quot;failed&quot;,
            &quot;result&quot; =&gt; {
                &quot;name&quot; =&gt; &quot;Brian&quot;,
                &quot;age&quot; =&gt; 22
            },
            &quot;rolled-back&quot; =&gt; true
        },
        {
            &quot;outcome&quot; =&gt; &quot;failed&quot;,
            &quot;failure-description&quot; =&gt; &quot;[JBAS-12345] Some failure message&quot;,
            &quot;rolled-back&quot; =&gt; true
        },
        {
            &quot;outcome&quot; =&gt; &quot;cancelled&quot;
        }
    ]
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="multi-server-responses"><a class="anchor" href="#multi-server-responses"></a><a class="link" href="#multi-server-responses">Multi-Server Responses</a></h5>
<div class="paragraph">
<p>Multi-server responses are provided by operations that target a Domain
Controller or secondary Host Controller and require the responder to apply
the operation on multiple servers and aggregate their results (e.g.
nearly all domain or host configuration updates.)</p>
</div>
<div class="paragraph">
<p>Multi-server operations are executed in several stages.</p>
</div>
<div class="paragraph">
<p>First, the operation may need to be applied against the authoritative
configuration model maintained by the Domain Controller (for
<code>domain.xml</code> confgurations) or a Host Controller (for a <code>host.xml</code>
configuration). If there is a failure at this stage, the operation is
automatically rolled back, with a response like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; {
        &quot;domain-failure-description&quot; =&gt; &quot;[JBAS-33333] Failed to apply X to the domain model&quot;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the operation was addressed to the domain model, in the next stage
the Domain Controller will ask each secondary Host Controller to apply it to
its local copy of the domain model. If any Host Controller fails to do
so, the Domain Controller will tell all Host Controllers to revert the
change, and it will revert the change locally as well. The response to
the client will look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;failure-description&quot; =&gt; {
        &quot;host-failure-descriptions&quot; =&gt; {
            &quot;hostA&quot; =&gt; &quot;[DOM-3333] Failed to apply to the domain model&quot;,
            &quot;hostB&quot; =&gt; &quot;[DOM-3333] Failed to apply to the domain model&quot;
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the preceding stages succeed, the operation will be pushed to all
affected servers. If the operation is successful on all servers, the
response will look like this (this example operation has a void
response, hence the result for each server is undefined):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {
        &quot;groupA&quot; =&gt; {
            &quot;serverA-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            },
            &quot;serverA-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            }
        },
        &quot;groupB&quot; =&gt; {
            &quot;serverB-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            },
            &quot;serverB-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            }
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The operation need not succeed on all servers in order to get an
<code>"outcome" &#8658; "success"</code> result. All that is required is that it succeed
on at least one server without the rollback policies in the rollout plan
triggering a rollback on that server. An example response in such a
situation would look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; undefined,
    &quot;server-groups&quot; =&gt; {
        &quot;groupA&quot; =&gt; {
            &quot;serverA-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            },
            &quot;serverA-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            }
        },
        &quot;groupB&quot; =&gt; {
            &quot;serverB-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined,
                    &quot;rolled-back&quot; =&gt; true
                }
            },
            &quot;serverB-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined,
                    &quot;rolled-back&quot; =&gt; true
                }
            },
            &quot;serverB-3&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host3&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;failed&quot;,
                    &quot;failure-description&quot; =&gt; &quot;[DOM-4556] Something didn't work right&quot;,
                    &quot;rolled-back&quot; =&gt; true
                }
            }
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, if the operation fails or is rolled back on all servers, an
example response would look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>{
    &quot;outcome&quot; =&gt; &quot;failed&quot;,
    &quot;server-groups&quot; =&gt; {
        &quot;groupA&quot; =&gt; {
            &quot;serverA-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            },
            &quot;serverA-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;success&quot;,
                    &quot;result&quot; =&gt; undefined
                }
            }
        },
        &quot;groupB&quot; =&gt; {
            &quot;serverB-1&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host1&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;failed&quot;,
                    &quot;result&quot; =&gt; undefined,
                    &quot;rolled-back&quot; =&gt; true
                }
            },
            &quot;serverB-2&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host2&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;failed&quot;,
                    &quot;result&quot; =&gt; undefined,
                    &quot;rolled-back&quot; =&gt; true
                }
            },
            &quot;serverB-3&quot; =&gt; {
                &quot;host&quot; =&gt; &quot;host3&quot;,
                &quot;response&quot; =&gt; {
                    &quot;outcome&quot; =&gt; &quot;failed&quot;,
                    &quot;failure-description&quot; =&gt; &quot;[DOM-4556] Something didn't work right&quot;,
                    &quot;rolled-back&quot; =&gt; true
                }
            }
        }
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="CLI_Recipes"><a class="anchor" href="#CLI_Recipes"></a><a class="link" href="#CLI_Recipes">11. CLI Recipes</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="properties"><a class="anchor" href="#properties"></a><a class="link" href="#properties">11.1. Properties</a></h3>
<div class="sect3">
<h4 id="adding-reading-and-removing-system-property-using-cli"><a class="anchor" href="#adding-reading-and-removing-system-property-using-cli"></a><a class="link" href="#adding-reading-and-removing-system-property-using-cli">11.1.1. Adding, reading and removing system property using CLI</a></h4>
<div class="paragraph">
<p>For standalone mode:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>$ ./bin/jboss-cli.sh --connect controller=IP_ADDRESS
[standalone@IP_ADDRESS:9990 /] /system-property=foo:add(value=bar)
[standalone@IP_ADDRESS:9990 /] /system-property=foo:read-resource
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {&quot;value&quot; =&gt; &quot;bar&quot;}
}
[standalone@IP_ADDRESS:9990 /] /system-property=foo:remove
{&quot;outcome&quot; =&gt; &quot;success&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For domain mode the same commands are used, you can add/read/remove
system properties for:<br>
All hosts and server instances in domain</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@IP_ADDRESS:9990 /] /system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /system-property=foo:remove</code></pre>
</div>
</div>
<div class="paragraph">
<p>Host and its server instances</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:remove</code></pre>
</div>
</div>
<div class="paragraph">
<p>Just one server instance</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:remove</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="overview-of-all-system-properties"><a class="anchor" href="#overview-of-all-system-properties"></a><a class="link" href="#overview-of-all-system-properties">11.1.2. Overview of all system properties</a></h4>
<div class="paragraph">
<p>Overview of all system properties in WildFly including OS system
properties and properties specified on command line using -D, -P or
--properties arguments.</p>
</div>
<div class="paragraph">
<p>Standalone</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@IP_ADDRESS:9990 /] /core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Domain</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@IP_ADDRESS:9990 /] /host=primary/core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)
[domain@IP_ADDRESS:9990 /] /host=primary/server=server-one/core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuration-9"><a class="anchor" href="#configuration-9"></a><a class="link" href="#configuration-9">11.2. Configuration</a></h3>
<div class="sect3">
<h4 id="list-subsystems"><a class="anchor" href="#list-subsystems"></a><a class="link" href="#list-subsystems">11.2.1. List Subsystems</a></h4>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /:read-children-names(child-type=subsystem)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; [
        &quot;batch&quot;,
        &quot;datasources&quot;,
        &quot;deployment-scanner&quot;,
        &quot;ee&quot;,
        &quot;ejb3&quot;,
        &quot;infinispan&quot;,
        &quot;io&quot;,
        &quot;jaxrs&quot;,
        &quot;jca&quot;,
        &quot;jdr&quot;,
        &quot;jmx&quot;,
        &quot;jpa&quot;,
        &quot;jsf&quot;,
        &quot;logging&quot;,
        &quot;mail&quot;,
        &quot;naming&quot;,
        &quot;pojo&quot;,
        &quot;remoting&quot;,
        &quot;resource-adapters&quot;,
        &quot;sar&quot;,
        &quot;security&quot;,
        &quot;threads&quot;,
        &quot;transactions&quot;,
        &quot;undertow&quot;,
        &quot;webservices&quot;,
        &quot;weld&quot;
    ]
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="list-description-of-available-attributes-and-childs"><a class="anchor" href="#list-description-of-available-attributes-and-childs"></a><a class="link" href="#list-description-of-available-attributes-and-childs">11.2.2. List description of available attributes and childs</a></h4>
<div class="paragraph">
<p>Descriptions, possible attribute type and values, permission and whether
expressions ( <em>$\{ &#8230;&#8203; }</em> ) are allowed from the underlying model are
shown by the read-resource-description command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=datasources/data-source=ExampleDS:read-resource-description
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;description&quot; =&gt; &quot;A JDBC data-source configuration&quot;,
        &quot;head-comment-allowed&quot; =&gt; true,
        &quot;tail-comment-allowed&quot; =&gt; true,
        &quot;attributes&quot; =&gt; {
            &quot;connection-url&quot; =&gt; {
                &quot;type&quot; =&gt; STRING,
                &quot;description&quot; =&gt; &quot;The JDBC driver connection URL&quot;,
                &quot;expressions-allowed&quot; =&gt; true,
                &quot;nillable&quot; =&gt; false,
                &quot;min-length&quot; =&gt; 1L,
                &quot;max-length&quot; =&gt; 2147483647L,
                &quot;access-type&quot; =&gt; &quot;read-write&quot;,
                &quot;storage&quot; =&gt; &quot;configuration&quot;,
                &quot;restart-required&quot; =&gt; &quot;no-services&quot;
            },
            &quot;driver-class&quot; =&gt; {
                &quot;type&quot; =&gt; STRING,
                &quot;description&quot; =&gt; &quot;The fully qualified name of the JDBC driver class&quot;,
                &quot;expressions-allowed&quot; =&gt; true,
                &quot;nillable&quot; =&gt; true,
                &quot;min-length&quot; =&gt; 1L,
                &quot;max-length&quot; =&gt; 2147483647L,
                &quot;access-type&quot; =&gt; &quot;read-write&quot;,
                &quot;storage&quot; =&gt; &quot;configuration&quot;,
                &quot;restart-required&quot; =&gt; &quot;no-services&quot;
            },
            &quot;datasource-class&quot; =&gt; {
                &quot;type&quot; =&gt; STRING,
                &quot;description&quot; =&gt; &quot;The fully qualified name of the JDBC datasource class&quot;,
                &quot;expressions-allowed&quot; =&gt; true,
                &quot;nillable&quot; =&gt; true,
                &quot;min-length&quot; =&gt; 1L,
                &quot;max-length&quot; =&gt; 2147483647L,
                &quot;access-type&quot; =&gt; &quot;read-write&quot;,
                &quot;storage&quot; =&gt; &quot;configuration&quot;,
                &quot;restart-required&quot; =&gt; &quot;no-services&quot;
            },
            &quot;jndi-name&quot; =&gt; {
                &quot;type&quot; =&gt; STRING,
                &quot;description&quot; =&gt; &quot;Specifies the JNDI name for the datasource&quot;,
                &quot;expressions-allowed&quot; =&gt; true,
                &quot;nillable&quot; =&gt; false,
                &quot;access-type&quot; =&gt; &quot;read-write&quot;,
                &quot;storage&quot; =&gt; &quot;configuration&quot;,
                &quot;restart-required&quot; =&gt; &quot;no-services&quot;
            },
           ...</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="view-configuration-as-xml-for-domain-model-or-host-model"><a class="anchor" href="#view-configuration-as-xml-for-domain-model-or-host-model"></a><a class="link" href="#view-configuration-as-xml-for-domain-model-or-host-model">11.2.3. View configuration as XML for domain model or host model</a></h4>
<div class="paragraph">
<p>Assume you have a host that is called "primary"</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=primary:read-config-as-xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>Just for the domain or standalone</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] :read-config-as-xml</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="take-a-snapshot-of-what-the-current-domain-is"><a class="anchor" href="#take-a-snapshot-of-what-the-current-domain-is"></a><a class="link" href="#take-a-snapshot-of-what-the-current-domain-is">11.2.4. Take a snapshot of what the current domain is</a></h4>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] :take-snapshot()
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;domain-results&quot; =&gt; {&quot;step-1&quot; =&gt; {&quot;name&quot; =&gt; &quot;JBOSS_HOME/domain/configuration/domain_xml_history/snapshot/20110908-165222603domain.xml&quot;}},
        &quot;server-operations&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="take-the-latest-snapshot-of-the-host.xml-for-a-particular-host"><a class="anchor" href="#take-the-latest-snapshot-of-the-host.xml-for-a-particular-host"></a><a class="link" href="#take-the-latest-snapshot-of-the-host.xml-for-a-particular-host">11.2.5. Take the latest snapshot of the host.xml for a particular host</a></h4>
<div class="paragraph">
<p>Assume you have a host that is called "primary"</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /]  /host=primary:take-snapshot
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; {
        &quot;domain-results&quot; =&gt; {&quot;step-1&quot; =&gt; {&quot;name&quot; =&gt; &quot;JBOSS_HOME/domain/configuration/host_xml_history/snapshot/20110908-165640215host.xml&quot;}},
        &quot;server-operations&quot; =&gt; undefined
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="how-to-get-interface-address"><a class="anchor" href="#how-to-get-interface-address"></a><a class="link" href="#how-to-get-interface-address">11.2.6. How to get interface address</a></h4>
<div class="paragraph">
<p>The attribute for interface is named "resolved-address". It&#8217;s a runtime
attribute so it does not show up in :read-resource by default. You have
to add the "include-runtime" parameter.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./jboss-cli.sh --connect
Connected to standalone controller at localhost:9990
[standalone@localhost:9990 /] cd interface=public
[standalone@localhost:9990 interface=public] :read-resource(include-runtime=true)
{
     &quot;outcome&quot; =&gt; &quot;success&quot;,
     &quot;result&quot; =&gt; {
         &quot;any&quot; =&gt; undefined,
         &quot;any-address&quot; =&gt; undefined,
         &quot;any-ipv4-address&quot; =&gt; undefined,
         &quot;any-ipv6-address&quot; =&gt; undefined,
         &quot;criteria&quot; =&gt; [(&quot;inet-address&quot; =&gt; expression &quot;${jboss.bind.address:127.0.0.1}&quot;)],
         &quot;inet-address&quot; =&gt; expression &quot;${jboss.bind.address:127.0.0.1}&quot;,
         &quot;link-local-address&quot; =&gt; undefined,
         &quot;loopback&quot; =&gt; undefined,
         &quot;loopback-address&quot; =&gt; undefined,
         &quot;multicast&quot; =&gt; undefined,
         &quot;name&quot; =&gt; &quot;public&quot;,
         &quot;nic&quot; =&gt; undefined,
         &quot;nic-match&quot; =&gt; undefined,
         &quot;not&quot; =&gt; undefined,
         &quot;point-to-point&quot; =&gt; undefined,
         &quot;public-address&quot; =&gt; undefined,
         &quot;resolved-address&quot; =&gt; &quot;127.0.0.1&quot;,
         &quot;site-local-address&quot; =&gt; undefined,
         &quot;subnet-match&quot; =&gt; undefined,
         &quot;up&quot; =&gt; undefined,
         &quot;virtual&quot; =&gt; undefined
     }
}
[standalone@localhost:9990 interface=public] :read-attribute(name=resolved-address)
{
     &quot;outcome&quot; =&gt; &quot;success&quot;,
     &quot;result&quot; =&gt; &quot;127.0.0.1&quot;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>It&#8217;s similar for domain, just specify path to server instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[domain@localhost:9990 /] /host=primary/server=server-one/interface=public:read-attribute(name=resolved-address)
{
    &quot;outcome&quot; =&gt; &quot;success&quot;,
    &quot;result&quot; =&gt; &quot;127.0.0.1&quot;
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="runtime"><a class="anchor" href="#runtime"></a><a class="link" href="#runtime">11.3. Runtime</a></h3>
<div class="sect3">
<h4 id="get-all-configuration-and-runtime-details-from-cli"><a class="anchor" href="#get-all-configuration-and-runtime-details-from-cli"></a><a class="link" href="#get-all-configuration-and-runtime-details-from-cli">11.3.1. Get all configuration and runtime details from CLI</a></h4>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>./bin/jboss-cli.sh -c command=&quot;:read-resource(include-runtime=true, recursive=true, recursive-depth=10)&quot;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="scripting"><a class="anchor" href="#scripting"></a><a class="link" href="#scripting">11.4. Scripting</a></h3>
<div class="sect3">
<h4 id="windows-and-press-any-key-to-continue-...-issue"><a class="anchor" href="#windows-and-press-any-key-to-continue-...-issue"></a><a class="link" href="#windows-and-press-any-key-to-continue-...-issue">11.4.1. Windows and "Press any key to continue &#8230;&#8203;" issue</a></h4>
<div class="paragraph">
<p>WildFly scripts for Windows end with "Press any key to continue &#8230;&#8203;".
This behavior is useful when script is executed by double clicking the
script but not when you need to invoke several commands from custom
script (e.g. 'bin/jboss-admin.bat --connect command=:shutdown').</p>
</div>
<div class="paragraph">
<p>To avoid "Press any key to continue &#8230;&#8203;" message you need to specify
NOPAUSE variable. Call 'set NOPAUSE=true' in command line before running
any WildFly 27 .bat script or include it in your custom script before
invoking scripts from WildFly.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="statistics"><a class="anchor" href="#statistics"></a><a class="link" href="#statistics">11.5. Statistics</a></h3>
<div class="sect3">
<h4 id="read-statistics-of-active-datasources"><a class="anchor" href="#read-statistics-of-active-datasources"></a><a class="link" href="#read-statistics-of-active-datasources">11.5.1. Read statistics of active datasources</a></h4>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)</code></pre>
</div>
</div>
<div class="paragraph">
<p>or</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/subsystem=datasources/data-source=ExampleDS:read-resource(include-runtime=true,recursive=true)</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="cli_deployment"><a class="anchor" href="#cli_deployment"></a><a class="link" href="#cli_deployment">11.6. Deployment</a></h3>
<div class="sect3">
<h4 id="cli-deployment-command"><a class="anchor" href="#cli-deployment-command"></a><a class="link" href="#cli-deployment-command">11.6.1. CLI <em>deployment</em> command</a></h4>
<div class="paragraph">
<p>In addition to the legacy <em>deploy</em>, <em>undeploy</em> and <em>deployment-info</em> commands,
that stay un-changed, the CLI offers a <em>deployment</em> command that properly
separates the various use cases encountered when managing deployments. This command
offers a simpler interface and should be the way to go when managing deployments.
New features will be added thanks to the <em>deployment</em> command, legacy commands will not evolve.
This document contains a summary of the capabilities of this command, type <em>help deployment</em>
to display the list of all available actions and <em>help deployment &lt;action&gt;</em> for the detailed
description of an action.</p>
</div>
<div class="paragraph">
<p>Actions to deploy some content:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>deployment deploy-file</em>: To deploy a file located on the file system.</p>
</li>
<li>
<p><em>deployment deploy-url</em>: To deploy content referenced by an URL.</p>
</li>
<li>
<p><em>deployment deploy-cli-achive</em>: To deploy some content thanks to a CLI archive
(.cli file) located on the file system.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Actions to enable some deployments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>deployment enable</em>: To enable a given disabled deployment.</p>
</li>
<li>
<p><em>deployment enable-all</em>: To enable all disabled deployments.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Actions to disable some deployments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>deployment disable</em>: To disable a given enabled deployment.</p>
</li>
<li>
<p><em>deployment disable-all</em>: To disable all enabled deployments.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Actions to undeploy some deployments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>deployment undeploy</em>: To undeploy a given deployment and remove its content
from the repository.</p>
</li>
<li>
<p><em>deployment undeploy-cli-archive</em>: To undeploy some content using a CLI archive
(.cli file) located on the file system.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Actions to get information on some deployments:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>deployment info</em>: To display information about single or multiple deployments.</p>
</li>
<li>
<p><em>deployment list</em>: To display all the existing deployments.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="incremental-deployment-with-the-cli"><a class="anchor" href="#incremental-deployment-with-the-cli"></a><a class="link" href="#incremental-deployment-with-the-cli">11.6.2. Incremental deployment with the CLI</a></h4>
<div class="paragraph">
<p>It can be desirable to incrementally create and(or) update a WildFly
deployment. This chapter details how this can be achieved using the
WildFly CLI tool.</p>
</div>
<div class="paragraph">
<p>Steps to create an empty deployment and add an index html file.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create an empty deployment named my app:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=myapp:add(content=[{empty=true}])</code></pre>
</div>
</div>
</li>
<li>
<p>Add an index.html to my app:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=&lt;press TAB&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then use completion to navigate to your index.html file.</p>
</div>
</li>
<li>
<p>Provide a target name for index.html inside the deployment and
execute the operation:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=./index.html, target-path=index.xhtml}]</code></pre>
</div>
</div>
</li>
<li>
<p>Your content has been added, you can browse the content of a
deployment using the browse-content operation:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>[standalone@localhost:9990 /] /deployment=myapp:browse-content(path=./)</code></pre>
</div>
</div>
</li>
<li>
<p>You can display (or save) the content of a deployed file using the
<em>attachement</em> command:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>attachment display --operation=/deployment=myapp:read-content(path=index.xhtml)</code></pre>
</div>
</div>
</li>
<li>
<p>You can remove content from a deployment:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>/deployment=myapp:remove-content(paths=[./index.xhtml])</code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>Tips</p>
</div>
<div class="ulist TIP">
<ul class="TIP">
<li>
<p><em>add-content</em> operation allows you to add more than one file (
<em>content</em> argument is a list of complex types).</p>
</li>
<li>
<p>CLI offers completion for <em>browse-conten</em>t&#8217;s <em>path</em> and
<em>remove-content</em>'s <em>paths</em> argument.</p>
</li>
<li>
<p>You can safely use operations that are using attached streams in batch
operations. In the case of batch operations, streams are attached to the
composite operation.</p>
</li>
</ul>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
On Windows, path separator '\' needs to be escaped, this is a limitation
of CLI handling complex types. The file path completion is automatically
escaping the paths it is proposing.
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="notes-for-server-side-operation-handler-implementors"><a class="anchor" href="#notes-for-server-side-operation-handler-implementors"></a><a class="link" href="#notes-for-server-side-operation-handler-implementors">Notes for server side operation Handler implementors</a></h5>
<div class="paragraph">
<p>In order to benefit from CLI support for attached file streams and file
system completion, you need to properly structure your operation
arguments. Steps to create an operation that receives a list of file
streams attached to the operation:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Define your operation argument as a <em>LIST</em> of <em>INT</em> (The <em>LIST</em>
<em>value-type</em> must be of type <em>INT</em>).</p>
</li>
<li>
<p>In the description of your argument, add the 2 following boolean
descriptors: <em>filesystem-path</em> and <em>attached-streams</em></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>When your operation is called from the CLI, file system completion will
be automatically proposed for your argument. At execution time, the file
system paths will be automatically converted onto the index of the
attached streams.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="downloading-files-with-the-cli"><a class="anchor" href="#downloading-files-with-the-cli"></a><a class="link" href="#downloading-files-with-the-cli">11.7. Downloading files with the CLI</a></h3>
<div class="paragraph">
<p>Some management resources are exposing the content of files in the
matter of <em>streams</em>. Streams returned by a management operation are
attached to the headers of the management response. The CLI command
<em>attachment</em> (see CLI help for a detailed description of this command)
allows to display or save the content of the attached streams.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Displaying the content of server.log file:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>attachment display --operation=/subsystem=logging/log-file=server.log:read-resource(include-runtime)</code></pre>
</div>
</div>
</li>
<li>
<p>Saving locally the server.log file:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>attachment save --operation=/subsystem=logging/log-file=server.log:read-resource(include-runtime) --file=./server.log</code></pre>
</div>
</div>
</li>
<li>
<p>Displaying the content of a deployed file:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>attachment display --operation=/deployment=myapp:read-content(path=index.xhtml)</code></pre>
</div>
</div>
</li>
</ul>
</div>
<div class="ulist TIP">
<ul class="TIP">
<li>
<p>By default existing files will be preserved. Use the option
<em>--overwrite</em> to overwrite existing file.</p>
</li>
<li>
<p><em>attachment</em> can be used in batch mode.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="iteration-of-collections"><a class="anchor" href="#iteration-of-collections"></a><a class="link" href="#iteration-of-collections">11.8. Iteration of Collections</a></h3>
<div class="paragraph">
<p>The command <em>for</em> allows to iterate the content of an operation result. As an
example, this command can be used to display the content of the Manifest files
present in all deployed applications. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>for deployed in :read-children-names(child-type=deployment)
 echo $deployed Manifest content
 attachment display --operation=/deployment=$deployed:read-content(path=META-INF/MANIFEST.MF)
done</code></pre>
</div>
</div>
<div class="paragraph">
<p>When this <em>for</em> block is executed, the content of all Manifest files is displayed in the CLI console.</p>
</div>
<div class="paragraph">
<p>Tips</p>
</div>
<div class="ulist TIP">
<ul class="TIP">
<li>
<p>The scope of the defined variable is limited to the <em>for</em> block.</p>
</li>
<li>
<p>If a variable with the same name already exists, the <em>for</em> command will print an error.</p>
</li>
<li>
<p>If the operation doesn&#8217;t return a list, the <em>for</em> command will print an error.</p>
</li>
<li>
<p><em>for</em> block can be discarded and not execute by adding the option <em>--discard</em> to <em>done</em>.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="cli-security-commands"><a class="anchor" href="#cli-security-commands"></a><a class="link" href="#cli-security-commands">11.9. Security Commands</a></h3>
<div class="paragraph">
<p>CLi offers a <em>security</em> command to group all security related management actions
under a single command.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security enable-ssl-management</em>: To enable SSL (elytron SSLContext) for the
management interfaces. Type <em>help security enable-ssl-management</em> for a
complete description of the command.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Among other ways to configure SSL, this command offers an interactive wizard to
help you configure SSL by generating a self-signed certificate.
Example of wizard usage:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code>security enable-ssl-management --interactive
Please provide required pieces of information to enable SSL:
Key-store file name (default management.keystore):
Password (blank generated):
What is your first and last name? [Unknown]:
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?
Validity (in days, blank default):
Alias (blank generated):
Enable SSL Mutual Authentication y/n (blank n):n

SSL options:
key store file: management.keystore
distinguished name: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
password: KRzne5s1
validity: default
alias: alias-265e6c6d-ff4e-4b8c-8f10-f015d678eb29
Server keystore file management.keystore, certificate signing request management.csr and
certificate file management.keystore.pem will be generated in server configuration directory.
Do you confirm y/n :y</code></pre>
</div>
</div>
<div class="paragraph">
<p>NB: Once the command is executed, the CLI will reload the server and reconnect to it.</p>
</div>
<div class="paragraph">
<p>This command can also obtain the certificates from the Let&#8217;s Encrypt certificate authority
by use of the --lets-encrypt parameter.
Besides the mentioned workflow the user will be prompted to specify more information
(eg: account key store, certificate authority account) to obtain the certificate from Let&#8217;s Encrypt.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security disable-ssl-management</em>: To disable SSL (elytron SSLContext) for the
management interfaces. Type <em>help security disable-ssl-management</em> for
a complete description of the command.</p>
</li>
<li>
<p><em>security enable-ssl-http-server</em>: To enable SSL (elytron SSLContext) for the
<em>undertow</em> server. The same wizard as the <em>enable-ssl-management</em> action is available.
Type <em>help security enable-ssl-http-server</em> for a complete description of the command.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This command can also obtain the certificates from the Let&#8217;s Encrypt certificate authority
by use of the --lets-encrypt parameter.
Besides the mentioned workflow the user will be prompted to specify more information
(eg: account key store, certificate authority account) to obtain the certificate from Let&#8217;s Encrypt.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security disable-ssl-http-server</em>: To disable SSL (elytron SSLContext) for the
<em>undertow</em> server. Type <em>help security disable-ssl-http-server</em> for a complete
description of the command.</p>
</li>
<li>
<p><em>security enable-sasl-management</em>: To enable SASL authentication (elytron SASL factory) for the
management interfaces. Calling this command without any option will have the
effect to associate the out of the box SASL factory to the http-interface.
Type <em>help security enable-sasl-management</em> for a complete description of the command.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This command supports a subset of SASL mechanisms such as: EXTERNAL, DIGEST-MD5,
JBOSS-LOCAL-USER, SCRAM-*, &#8230;&#8203; The CLI completer proposes the set of mechanisms that
can be properly configured using this command. Each mechanism can be associated
to a property file realm, a file-system realm or a trust-store realm according to its nature.</p>
</div>
<div class="paragraph">
<p>NB: Once the command is executed, the CLI will reload the server and reconnect to it.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security disable-sasl-management</em>: To disable SASL for the
management interfaces. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the interface. Without mechanism, the
factory is no more active on the management interface. Type <em>help security disable-sasl-management</em>
for a complete description of the command.</p>
</li>
<li>
<p><em>security reorder-sasl-management</em>: To re-order the list of SASL mechanisms present
in the factory. Order of mechanisms is of importance, the first in the list is sent to the client.
Type <em>help security reorder-sasl-management</em> for a complete description of the command.</p>
</li>
<li>
<p><em>security enable-http-auth-management</em>: To enable HTTP authentication (elytron HTTP factory) for the
management http-interface. Calling this command without any option will have the
effect to associate the out of the box HTTP Authentication factory to the http-interface.
Type <em>help security enable-http-auth-management</em> for a complete description of the command.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This command supports a subset of HTTP mechanisms such as: BASIC, CLIENT_CERT, DIGEST, &#8230;&#8203;
The CLI completer proposes the set of mechanisms that can be properly configured
using this command. Each mechanism can be associated to a property file realm,
a file-system realm or a trust-store realm according to its nature.</p>
</div>
<div class="paragraph">
<p>NB: Once the command is executed, the CLI will reload the server and reconnect to it.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security disable-http-auth-management</em>: To disable HTTP Authentication for the
http management interface. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the interface. Without mechanism, the
factory is no more active on the management interface. Type <em>help security disable-http-auth-management</em>
for a complete description of the command.</p>
</li>
<li>
<p><em>security enable-http-auth-http-server</em>: To enable HTTP authentication (elytron HTTP factory) for the
given undertow security domain.
Type <em>help security enable-http-auth-http-server</em> for a complete description of the command.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This command supports a subset of HTTP mechanisms such as: BASIC, CLIENT_CERT, DIGEST, &#8230;&#8203;
The CLI completer proposes the set of mechanisms that can be properly configured
using this command. Each mechanism can be associated to a property file realm,
a file-system realm or a trust-store realm according to its nature.</p>
</div>
<div class="paragraph">
<p>NB: Once the command is executed, the CLI will reload the server and reconnect to it.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>security disable-http-auth-http-server</em>: To disable HTTP Authentication for the
given undertow security domain. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the security domain. Without mechanism, the
factory is no more active on the security-domain. Type <em>help security disable-http-auth-http-server</em>
for a complete description of the command.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="mp-cli-script"><a class="anchor" href="#mp-cli-script"></a><a class="link" href="#mp-cli-script">11.10. Evolving standard configurations with support for MicroProfile</a></h3>
<div class="paragraph">
<p>The CLI script <em>JBOSS_HOME/docs/examples/enable-microprofile.cli</em> can be applied to a default standalone configuration
to add support for MicroProfile.</p>
</div>
<div class="paragraph">
<p>Impact on updated configuration:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Addition of MicroProfile subsystems.</p>
</li>
<li>
<p>Removal of <em>security</em> subsystem.</p>
</li>
<li>
<p>Removal of <em>ManagementRealm</em>.</p>
</li>
<li>
<p>Elytron security used for management and application entry points.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default the script updates <em>standalone.xml</em> configuration.
Thanks to the <em>config=&lt;config name&gt;</em> system property, the script can be applied to another standalone configuration.</p>
</div>
<div class="paragraph">
<p>NB: this script has to be applied <em>offline</em> with no server running.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>To update <em>standalone.xml</em> server configuration:</p>
<div class="ulist">
<ul>
<li>
<p><em>./bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli</em></p>
</li>
</ul>
</div>
</li>
<li>
<p>To update other standalone server configurations:</p>
<div class="ulist">
<ul>
<li>
<p><em>./bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli
-Dconfig=&lt;standalone-full.xml|standalone-ha.xml|standalone-full-ha.xml&gt;</em></p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 27.0.0.Final<br>
Last updated 2022-01-12 11:25:45 -0600
</div>
</div>
</body>
</html>