lauracowen commented 4 years ago

Two KC topics:

Alasdair's comments: this is really confusing and no one understands how to do it; it comes up relatively often. Probably needs a re-write.

In cloud - virtual hosts stuff allows you to: separate out the traffic that you want to exposed as part of app on a different port number from traffic that integrate into your cloud system. eg MP Metrics runs on same port as application and people often don't want the metrics accessible on same port to outside world. Useful if you're running multiple apps on same JVM (not cloud-y but useful in that case); allows you to do stuff with host name - when you define virtual host, you say which host name it should be requested through. Always find this difficult to explain to people and get right - the KC topic isn't helpful.

Mediium priority but if we move it across, it needs a re-write. Should be single topic re-written together (not two separate topics as in KC).

Charlotte-Holt commented 3 years ago

Update the spreadsheet when done.

Charlotte-Holt commented 3 years ago

Try to incorporate the necessary info from this Liberty KC doc bug: https://github.ibm.com/websphere/liberty-docs/issues/911

Charlotte-Holt commented 3 years ago

After this topic is complete, the "Configure applications to run on a virtual host" link in Network Hardening under Security Hardening topic (https://openliberty.io/docs/20.0.0.12/security-hardening.html) needs to link to this topic.

Charlotte-Holt commented 3 years ago

In the virtual hosts topic, cover comment from https://github.com/openliberty/docs/issues/3417 "Configure applications to run on a virtual host" is not sufficient for a hardened configuration - the requirement is that there should not be a hostAlias that matches to * in a hardened configuration."

Rwalls1 commented 3 years ago

@wtlucy Can you confirm which information from the two KC topics is most relevant or most important to OL users?

wtlucy commented 3 years ago

Hi @Rwalls1, I've reviewed both of these documents, and they both have helpful content - however if I had to choose a single one I'd choose Using virtual hosts. The other document Virtual hosts contains long textual descriptions of common scenarios - it might make sense for us to work some that content into the more readable format used by Virtual hosts.

Rwalls1 commented 3 years ago

@wtlucy Thanks, when reviewing both docs and doing further research, I haven't been able to identify a consistently defined purpose or primary benefit for using virtual hosts. How would you describe the main advantage or primary benefits of using virtual hosts with OL?

wtlucy commented 3 years ago

From the Liberty point of view, the most important function of virtual hosting is that it provides the ability for a single server instance to provide different (multiple) applications on different host and port combinations. That basic functionality allows apps to be isolated based on those hosts and ports.

Rwalls1 commented 3 years ago

SME: Bill Lucy

Rwalls1 commented 3 years ago

Content proposal

Configuring virtual hosts

Short description: Virtual hosts provide a way to run multiple applications on the same server. You can configure virtual hosts to isolate applications to reduce the traffic that is needed to host applications.

Intro

Describe the connection between the requests to access applications and the host name and port number configurations that define each request. Highlight the function of using virtual hosts to isolate applications based on those host name and port number configurations explain why that's important (reduce number of servers needed to host your applications). Use the description of the virtual host configuration from the "Virtual hosts" doc to define the concept. Introduce the sections from the "Using virtual hosts" doc as common use cases for configuring virtual hosts:

Isolating two applications from each other
Isolating applications based on the requested host or port
Restricting access based on originating endpoint

While each of these use case sections will need to be rewritten, I think it makes sense to provide some key scenarios that help to understand how to configure virtual hosts and when they might be useful. These use cases from the "Using virtual hosts" are a bit confusing due to the lack of conceptual info to support the procedures, so I think there's some helpful info from the "Virtual hosts" doc that should be added to these sections to provide more context.

dmuelle commented 3 years ago

Hi @wtlucy, initial draft is now available for review:

https://draft-openlibertyio.mybluemix.net/docs/21.0.0.10/virtual-hosts.html

dmuelle commented 3 years ago

@wtlucy A few questions:

The virtual host configuration uses wildcard entries with the ports for its virtual host entries.

This seems to suggest that a virtual host always uses a wildcard. Is that the case? Is would it be more accurate to say something like: The virtual host configuration accepts a wildcard value (*) for the hostname for its virtual host entries.

The default alias is *:80, which uses an external port that is not secure.

What does "default alias" mean here? Is it the default alias for default_host ? Or for any virtual host that you dont delcare an alias for? What if there are multiple v hosts that dont declare an alias?

Furthermore, the virtual host configuration for application-2 specifies that this application is available only on the localhost interface

is the advantage of only accepting traffic from localhost that the app only takes requests from the machine where it is running (therefore a test or internal app?)

Restrict access to an application based on the originating endpoint

Why/when would you do this? How using is allowFromEndpointRef different from restricting requests to the app by defining endpoints by alias (if that makes sense)?

wtlucy commented 3 years ago

The virtual host configuration uses wildcard entries with the ports for its virtual host entries.

This is confusing as written. A wildcard is not always used. These are the default aliases, so I'm wondering if that was the intention of this section. Your proposed replacement makes more sense to me.

The default alias is *:80, which uses an external port that is not secure.

This covers both default_host as well as any virtual host that you don't declare an alias for. For multiple vhosts with no aliases declared, I don't think the server will throw a config error, however the matching behavior would be undefined.

Furthermore, the virtual host configuration for application-2 specifies that this application is available only on the localhost interface

Yes, that's my understanding

Restrict access to an application based on the originating endpoint

The distinction to make here is that the virtualhost aliases can make use of the Host HTTP header, while the httpEndpoint configurations discriminate based on what we get from the system network interfaces.

dmuelle commented 3 years ago

Thanks @wtlucy. Draft is updated per our discussion:

https://draft-openlibertyio.mybluemix.net/docs/latest/virtual-hosts.html

When you have a chance, let me know if the updates look ok or if any further edits are needed. If not, you can add the technical reviewed label to this issue to sign off.

wtlucy commented 3 years ago

Thanks for making these changes @dmuelle. I've just gone over the updated draft and have a few more (new) requests:

The term DNS alias is used a few times, and I don't think it's really correct in context. Can we perhaps change that term to host alias?
...is the TCP/IP hostname and port number combination that is used to request the servlet... -> ..is the TCP/IP hostname and port number combination that is used to request a resource...

And a few non-technical comments:

the list Aliases of the form... under "Virtual Host Aliases" isn't formatted correctly
the code block for the "wildcard value" under "Virtual Host Aliases" has an extra trailing tick `
the link to Network security hardening isn't pointing to the correct page (not sure if this is just a draft problem)
the third paragraph under "Isolate applications on the same server" has a code block missing a trailing ", virtual-host name="application-1

dmuelle commented 3 years ago

Thanks for reviewing @wtlucy - I've updated the draft per your comments:

https://draft-openlibertyio.mybluemix.net/docs/latest/virtual-hosts.html

[x] The term DNS alias is used a few times, and I don't think it's really correct in context. Can we perhaps change that term to host alias?
[x] ...is the TCP/IP hostname and port number combination that is used to request the servlet... -> ..is the TCP/IP hostname and port number combination that is used to request a resource..._
[x] the list Aliases of the form... under "Virtual Host Aliases" isn't formatted correctly
[x] the code block for the "wildcard value" under "Virtual Host Aliases" has an extra trailing tick `
[x] the link to Network security hardening isn't pointing to the correct page (not sure if this is just a draft problem)
[x] the third paragraph under "Isolate applications on the same server" has a code block missing a trailing ", virtual-host name="application-1

Apologies for the typos, should've checked the draft more carefully before I sent it back.

wtlucy commented 3 years ago

@dmuelle the draft looks good to me now - thanks!

ManasiGandhi commented 3 years ago

@dmuelle The doc looks good! Had a few edit suggestions.

Peer review

[x] Good use of the example for explaining the concepts. You could usecustomer.example.com instead of customer.exampleco.com, also for employee. Also, are customer.exampleco.com and employee.exampleco.com endpoints or urls, as the only differentiator between them is the host? An endpoint is usually something like example.com/login, or example.com/accounts, where /login or /accounts is the endpoint, is my understanding.

Virtual host aliases
[x] “Each virtual host has a name and a list of one or more host aliases by which it is known. A host alias is the TCP/IP hostname and port number combination that is used to request a resource, for example, yourHostName:80. ” Is a host alias the same as DNS alias? It says here that “Each virtual host has a logical name and a list of one or more DNS aliases by which it is known.” I know Bill commented to use host alias, but the first sentence says, “Each virtual host has a name and a list of one or more host aliases”, and the second sentence says, “A host alias is the TCP/IP hostname and port number combination”, so does each virtual host have a name+list of one or more host aliases which also means name+host alias or name+hostname+port number, which is a bit confusing. So, in name+hostname+port number, is there a difference between name and hostname? (sorry for the long-winded question)
[x] "When no port number is specified, the default is 80"? – maybe "When no port number is specified, the default port number is 80, for clarity.
[x] “The default alias is*:80, which uses an external port that is not secure. ”, probably, “The default alias for a virtual host is *:80, which uses an external port that is not secure. ” also, “The configuration of an alias determines whether a virtual host uses secure ports, and whether the ports are internal or external:” to, “The configuration of a virtual host alias determines whether a virtual host uses secure ports, and whether the ports are internal or external:”, for clarity.
[ ] Are these for the default virtual hosts as mentioned here? Should it specifically say default virtual host aliases? o Aliases of the form :9080 use the internal port that is not secure. o Aliases of the form :9443 use the secure internal port. o Aliases of the form *:443 use the secure external port.

Virtual hosts and application security in production environments

[x] Instead of "For more information, see Network security hardening", maybe "For more information, see Virtual hosts" as you're planning to change the title.

Virtual host configuration

Isolate applications based on the requested host or port

[x] "The default virtual host in Open Liberty, default_host, is used for JMX communications." Is that the only use case for the default virtual host in Open Liberty?

dmuelle commented 3 years ago

Thanks for reviewing @ManasiGandhi - I've made all the suggested changes except:

Are these for the default virtual hosts as mentioned here? Should it specifically say default virtual host aliases?

The KC doc is confusing on this- these are not default aliases. They are examples of possible alias configurations that explain whether the config uses internal/external or secure/insecure ports. ie, if you specify *:9080 as an alias config, the alias uses the internal port that is not secure.

https://draft-openlibertyio.mybluemix.net/docs/21.0.0.10/virtual-hosts.html

I checked with Bill w/r/t endpoints vs URL (good question). I haven't heard back het. I updated the doc to use URL but will edit per his suggestion as needed. Update: Bill agrees "URL" is suitable for this example case
"Each virtual host has a name..." I changed this to Each virtual host has an ID value..." to avoid confusion between the name of the host (ID) and the hostname of the alias

dmuelle commented 3 years ago

changes on vNext, doc will publish with 21.0.0.10

OpenLiberty / docs

Suggested topic: using virtual hosts #3318

Content proposal

Configuring virtual hosts

Intro

Peer review

Virtual host aliases

Virtual hosts and application security in production environments

Virtual host configuration

Isolate applications based on the requested host or port