Skip to content

Commit 0cd08f2

Browse files
MarkEWaiteMarkEWaite
authored
Merge pull request #525 from daniel-beck/control-port-docs
Improve (and fix) options documentation
2 parents fd07a7c + bebe91b commit 0cd08f2

File tree

2 files changed

+88
-78
lines changed

2 files changed

+88
-78
lines changed

‎README.md‎

Lines changed: 82 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -40,82 +40,88 @@ To run locally exploded web archive:
4040

4141
## Command-line options
4242

43-
Winstone Servlet Engine, (c) 2003-2006 Rick Knowles
44-
Usage: java winstone.jar [--option=value] [--option=value] [etc]
45-
46-
Required options: either --webroot OR --warfile
47-
--webroot = set document root folder.
48-
--warfile = set location of warfile to extract from.
49-
Other options:
50-
--javaHome = Override the JAVA_HOME variable
51-
--config = load configuration properties from here. Default is ./winstone.properties
52-
--prefix = add this prefix to all URLs (eg http://localhost:8080/prefix/resource). Default is none
53-
--commonLibFolder = folder for additional jar files. Default is ./lib
54-
55-
--logfile = redirect log messages to this file
56-
--logThrowingLineNo = show the line no that logged the message (slow). Default is false
57-
--logThrowingThread = show the thread that logged the message. Default is false
58-
--debug = set the level of Winstone debug msgs (1-9). Default is 5 (INFO level)
59-
60-
--httpPort = set the http listening port. -1 to disable, Default is 8080
61-
--httpListenAddress = set the http listening address. Default is all interfaces
62-
--httpUnixDomainPath = set the http unix domain path. Default is no path
63-
--httpKeepAliveTimeout = how long idle HTTP keep-alive connections are kept around (in ms; default 30000)?
64-
--httpsPort = set the https listening port. -1 to disable, Default is disabled
65-
--httpsListenAddress = set the https listening address. Default is all interfaces
66-
--httpsKeepAliveTimeout = how long idle HTTPS keep-alive connections are kept around (in ms; default 30000)?
67-
--httpsKeyStore = the location of the SSL KeyStore file. Default is ./winstone.ks
68-
--httpsKeyStorePassword = the password for the SSL KeyStore file. Default is null
69-
--httpsKeyStoreType = set the HTTPS keystore type (JKS, PKCS12, BCFKS, etc.).
70-
Default is the Java default keystore type.
71-
--httpsKeyManagerType = the SSL KeyManagerFactory type (eg SunX509, IbmX509). Default is SunX509
72-
--httpsRedirectHttp = redirect http requests to https (requires both --httpPort and --httpsPort)
73-
--http2Port = set the http2 listening port. -1 to disable, Default is disabled
74-
--httpsSniHostCheck = if the SNI Host name must match when there is an SNI certificate. Check disabled per default
75-
--httpsSniRequired = if a SNI certificate is required. Disabled per default
76-
--http2ListenAddress = set the http2 listening address. Default is all interfaces
77-
--excludeProtocols = set protocol versions to exclude. (comma separated list, use blank quote " " to exclude none)
78-
(default is "SSL", "SSLv2", "SSLv2Hello", "SSLv3")
79-
--excludeCipherSuites = set the ciphers to exclude (comma separated, use blank quote " " to exclude none) (default is
80-
// Exclude weak / insecure ciphers
81-
"^.*_(MD5|SHA|SHA1)$",
82-
// Exclude ciphers that don't support forward secrecy
83-
"^TLS_RSA_.*$",
84-
// The following exclusions are present to cleanup known bad cipher
85-
// suites that may be accidentally included via include patterns.
86-
// The default enabled cipher list in Java will not include these
87-
// (but they are available in the supported list).
88-
"^SSL_.*$",
89-
"^.*_NULL_.*$",
90-
"^.*_anon_.*$"
91-
--controlPort = set the shutdown/control port. -1 to disable, Default disabled
92-
93-
--compression = set the compression scheme (gzip or none to disable compression). Default is gzip.
94-
--sessionTimeout = set the http session timeout value in minutes. Default to what webapp specifies, and then to 60 minutes
95-
--sessionEviction = set the session eviction timeout for idle sessions in seconds. Default value is 1800 (30 minutes). -1 never evict, 0 evict on exit
96-
--mimeTypes=ARG = define additional MIME type mappings. ARG would be EXT=MIMETYPE:EXT=MIMETYPE:...
97-
(e.g., xls=application/vnd.ms-excel:wmf=application/x-msmetafile)
98-
--requestHeaderSize=N = set the maximum size in bytes of the request header. Default is 8192.
99-
--responseHeaderSize=N = set the maximum size in bytes of the response header. Default is 32768.
100-
--maxParamCount=N = set the max number of parameters allowed in a form submission to protect
101-
against hash DoS attack (oCERT #2011-003). Default is 10000.
102-
--useJmx = Enable Jetty Jmx
103-
--qtpMaxThreadsCount = max threads number when using Jetty Queued Thread Pool
104-
--jettyAcceptorsCount = Jetty Acceptors number
105-
--jettySelectorsCount = Jetty Selectors number
106-
--usage / --help = show this message
107-
Security options:
108-
--realmClassName = Set the realm class to use for user authentication. Defaults to ArgumentsRealm class
109-
110-
--argumentsRealm.passwd.<user> = Password for user <user>. Only valid for the ArgumentsRealm realm class
111-
--argumentsRealm.roles.<user> = Roles for user <user> (comma separated). Only valid for the ArgumentsRealm realm class
112-
113-
--fileRealm.configFile = File containing users/passwds/roles. Only valid for the FileRealm realm class
114-
115-
Access logging:
116-
--accessLoggerClassName = Set the access logger class to use for user authentication. Defaults to disabled
117-
--simpleAccessLogger.format = The log format to use. Supports combined/common/resin/custom (SimpleAccessLogger only)
118-
--simpleAccessLogger.file = The location pattern for the log file(SimpleAccessLogger only)
43+
```
44+
Winstone Servlet Engine, (c) 2003-2006 Rick Knowles
45+
Usage: java winstone.jar [--option=value] [--option=value] [etc]
46+
47+
Required options: either --webroot OR --warfile
48+
--webroot = set document root folder.
49+
--warfile = set location of warfile to extract from.
50+
Other options:
51+
--javaHome = Override the JAVA_HOME variable
52+
--config = load configuration properties from here. Default is ./winstone.properties
53+
--prefix = add this prefix to all URLs (eg http://localhost:8080/prefix/resource). Default is none
54+
--commonLibFolder = folder for additional jar files. Default is ./lib
55+
56+
--logfile = redirect log messages to this file
57+
--logThrowingLineNo = show the line no that logged the message (slow). Default is false
58+
--logThrowingThread = show the thread that logged the message. Default is false
59+
--debug = set the level of Winstone debug msgs (1-9). Default is 5 (INFO level)
60+
61+
--httpPort = set the http listening port. -1 to disable, Default is 8080
62+
--httpListenAddress = set the http listening address. Default is all interfaces
63+
--httpUnixDomainPath = set the http unix domain path. Default is no path
64+
--httpKeepAliveTimeout = how long idle HTTP keep-alive connections are kept around (in ms; default 30000)?
65+
--httpsPort = set the https listening port. -1 to disable, Default is disabled
66+
--httpsListenAddress = set the https listening address. Default is all interfaces
67+
--httpsKeepAliveTimeout = how long idle HTTPS keep-alive connections are kept around (in ms; default 30000)?
68+
--httpsKeyStore = the location of the SSL KeyStore file. Default is ./winstone.ks
69+
--httpsKeyStorePassword = the password for the SSL KeyStore file. Default is null
70+
--httpsKeyStoreType = set the HTTPS keystore type (JKS, PKCS12, BCFKS, etc.).
71+
Default is the Java default keystore type.
72+
--httpsKeyManagerType = the SSL KeyManagerFactory type (eg SunX509, IbmX509). Default is SunX509
73+
--httpsRedirectHttp = redirect http requests to https (requires both --httpPort and --httpsPort)
74+
--http2Port = set the http2 listening port. -1 to disable, Default is disabled
75+
--httpsSniHostCheck = if the SNI Host name must match when there is an SNI certificate. Check disabled per default
76+
--httpsSniRequired = if a SNI certificate is required. Disabled per default
77+
--http2ListenAddress = set the http2 listening address. Default is all interfaces
78+
--httpsVerifyClient = if the client needs a certificate. Can be true (clients always needs a certificate),
79+
optional or false.
80+
--excludeProtocols = set protocol versions to exclude. (comma separated list, use blank quote " " to exclude none)
81+
(default is "SSL", "SSLv2", "SSLv2Hello", "SSLv3")
82+
--excludeCipherSuites = set the ciphers to exclude (comma separated, use blank quote " " to exclude none) (default is
83+
// Exclude weak / insecure ciphers
84+
"^.*_(MD5|SHA|SHA1)$",
85+
// Exclude ciphers that don't support forward secrecy
86+
"^TLS_RSA_.*$",
87+
// The following exclusions are present to cleanup known bad cipher
88+
// suites that may be accidentally included via include patterns.
89+
// The default enabled cipher list in Java will not include these
90+
// (but they are available in the supported list).
91+
"^SSL_.*$",
92+
"^.*_NULL_.*$",
93+
"^.*_anon_.*$"
94+
--controlPort = set the shutdown/control port. Not intended for production use. There are no security controls,
95+
limit access to the port to trusted hosts. -1 to disable, Default disabled
96+
97+
--compression = set the compression scheme (gzip or none to disable compression). Default is gzip.
98+
--sessionTimeout = set the http session timeout value in minutes. Default to what webapp specifies, and then to 60 minutes
99+
--sessionEviction = set the session eviction timeout for idle sessions in seconds.
100+
Default value is 1800 (30 minutes). -1 never evict, 0 evict on exit
101+
--mimeTypes=ARG = define additional MIME type mappings. ARG would be EXT=MIMETYPE:EXT=MIMETYPE:...
102+
(e.g., xls=application/vnd.ms-excel:wmf=application/x-msmetafile)
103+
--requestHeaderSize=N = set the maximum size in bytes of the request header. Default is 8192.
104+
--responseHeaderSize=N = set the maximum size in bytes of the response header. Default is 32768.
105+
--maxParamCount=N = set the max number of parameters allowed in a form submission to protect
106+
against hash DoS attack (oCERT #2011-003). Default is 10000.
107+
--useJmx = Enable Jetty Jmx
108+
--qtpMaxThreadsCount = max threads number when using Jetty Queued Thread Pool
109+
--jettyAcceptorsCount = Jetty Acceptors number
110+
--jettySelectorsCount = Jetty Selectors number
111+
--usage / --help = show this message
112+
Security options:
113+
--realmClassName = Set the realm class to use for user authentication. Defaults to ArgumentsRealm class
114+
115+
--argumentsRealm.passwd.<user> = Password for user <user>. Only valid for the ArgumentsRealm realm class
116+
--argumentsRealm.roles.<user> = Roles for user <user> (comma separated). Only valid for the ArgumentsRealm realm class
117+
118+
--fileRealm.configFile = File containing users/passwds/roles. Only valid for the FileRealm realm class
119+
120+
Access logging:
121+
--accessLoggerClassName = Set the access logger class to use for user authentication. Defaults to disabled
122+
--simpleAccessLogger.format = The log format to use. Supports combined/common/resin/custom (SimpleAccessLogger only)
123+
--simpleAccessLogger.file = The location pattern for the log file(SimpleAccessLogger only)
124+
```
119125

120126
## Configuration file
121127
You don't really need a config file, but sometimes it's handy to

‎src/main/resources/winstone/LocalStrings.properties‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ Launcher.UsageInstructions.Options=\
6464
\ --httpsKeepAliveTimeout = how long idle HTTPS keep-alive connections are kept around (in ms; default 30000)?\n\
6565
\ --httpsKeyStore = the location of the SSL KeyStore file. Default is ./winstone.ks\n\
6666
\ --httpsKeyStorePassword = the password for the SSL KeyStore file. Default is null\n\
67+
\ --httpsKeyStoreType = set the HTTPS keystore type (JKS, PKCS12, BCFKS, etc.).\n\
68+
\ Default is the Java default keystore type.\n\
6769
\ --httpsKeyManagerType = the SSL KeyManagerFactory type (eg SunX509, IbmX509). Default is SunX509\n\
6870
\ --httpsRedirectHttp = redirect http requests to https (requires both --httpPort and --httpsPort)\n\
6971
\ --http2Port = set the http2 listening port. -1 to disable, Default is disabled\n\
@@ -86,10 +88,12 @@ Launcher.UsageInstructions.Options=\
8688
\ "^SSL_.*$", \n\
8789
\ "^.*_NULL_.*$", \n\
8890
\ "^.*_anon_.*$" \n\
89-
\ --controlPort = set the shutdown/control port. -1 to disable, Default disabled\n\n\
91+
\ --controlPort = set the shutdown/control port. Not intended for production use. There are no security controls,\n\
92+
\ limit access to the port to trusted hosts. -1 to disable, Default disabled\n\n\
9093
\ --compression = set the compression scheme (gzip or none to disable compression). Default is gzip.\n\
9194
\ --sessionTimeout = set the http session timeout value in minutes. Default to what webapp specifies, and then to 60 minutes\n\
92-
\ --sessionEviction = set the session eviction timeout for idle sessions in seconds. Default value is 180. -1 never evict, 0 evict on exit\n\
95+
\ --sessionEviction = set the session eviction timeout for idle sessions in seconds.\n\
96+
\ Default value is 1800 (30 minutes). -1 never evict, 0 evict on exit\n\
9397
\ --mimeTypes=ARG = define additional MIME type mappings. ARG would be EXT=MIMETYPE:EXT=MIMETYPE:...\n\
9498
\ (e.g., xls=application/vnd.ms-excel:wmf=application/x-msmetafile)\n\
9599
\ --requestHeaderSize=N = set the maximum size in bytes of the request header. Default is 8192.\n\

0 commit comments

Comments
 (0)