OpenXRI:ServerQuickStart
From I-names Development Wiki
This page describes how to set up the OpenXRI authority resolution server for its most common use case, which is managing XRI subsegments and authorities in a part of the XRI address space for which you are authoritative.
This is similar in concept to setting up a DNS nameserver for managing subdomains under your domain name.
For more detailed information and more tutorials please see the OpenXRI Server User Manual.
Note: For now, it is recommended to check out and build OpenXRI yourself, instead of downloading the pre-built binary files. We should do an OpenXRI maintenance release soon. For information on building OpenXRI, see OpenXRI:SettingUpBuildEnvironment.
Contents |
Scenario
For the purpose of this tutorial, let's assume that you control the XRI =yourname and want to set up "child" XRI subsegments under it, e.g. =yourname*test. Let us further assume that the CanonicalID (aka i-number) of =yourname (i.e. the corresponding persistent identifier) is =!91F2.8153.F600.AE24.
This tutorial explains how to set up and configure the OpenXRI server to be authoritative for XRIs under =yourname.
From the perspective of your OpenXRI server, =yourname is called a root namespace, and *test is called an XRI subsegment under the root namespace. Every XRI subsegment has an associated XRI authority, which is a database object that holds an XRD descriptor document. When an XRI client (e.g. an XRI proxy resolver) tries to resolve an XRI such as =yourname*test, it obtains XRD descriptor documents for the authority of each subsegment of the XRI that is being resolved.
A single OpenXRI server can manage multiple root namespaces. Also, it can be deployed at any level in the XRI address space. For example, =yourname*test could be your root namespace, and you could then set up "child" XRI subsegments such as =yourname*test*more.
Preparation
In order for XRI resolution to work, the XRD descriptor document of each subsegment must point to a server that is responsible for subsegments further down in the hierarchy. For example, in order to set up an OpenXRI server with =yourname as your root namespace, you need to make sure that the XRD descriptor document of =yourname correctly points to your server. This is achieved with an authority resolution service endpoint (SEP), which should look like this:
<Service priority="10"> <ProviderID>xri://=!91F2.8153.F600.AE24</ProviderID> <Type select="true">xri://$res*auth*($v*2.0)</Type> <MediaType select="true">application/xrds+xml</MediaType> <URI append="qxri" priority="1">https://yourserver.com/openxri-server/resolve/ns/=!91F2.8153.F600.AE24/</URI> <URI append="qxri" priority="2">http://yourserver.com/openxri-server/resolve/ns/=!91F2.8153.F600.AE24/</URI> </Service>
This service endpoint effectively makes your OpenXRI server authoritative for XRI subsegments under =yourname. The process of setting up this service endpoint varies depending on where and how you got your root namespace XRI. It could be configured in another higher level OpenXRI server, or via a web interface, or by using the EPP protocol to talk to an XRI registry, etc.
The following diagram explains how the <URI> values in the above SEP are composed:
https://yourserver.com/openxri-server/resolve/ns/=!91F2.8153.F600.AE24/ [--------- 1 ---------|------2-------|---3---|-----------4------------] 1: The host name (and optionally port) of your server. 2: The context path to the OpenXRI server web application. This depends on the servlet container you are using (e.g. Tomcat), and on how exactly you deploy the web application. 3: This is the path to the OpenXRI authority resolution servlet. It can be changed in the WEB-INF/web.xml file of the OpenXRI server. 4: This is a path that is added as a parameter. It is a "hint" for the OpenXRI server to know which one of its root namespaces a request applies to.
When an XRI client (e.g. an XRI proxy resolver) tries to resolve anything under the above root namespace, it will take the <URI> value (which is completely opaque to the client) and add the name of the subsegment it is trying to resolve, e.g.:
https://yourserver.com/openxri-server/resolve/ns/=!91F2.8153.F600.AE24/*test
The OpenXRI server will respond with an XRD descriptor document for =yourname*test.
Deploying the OpenXRI server
To install the OpenXRI server, download the .WAR file by following the links at
http://openxri.org/server.html
You will need a Java servlet container (e.g. Tomcat) for running the OpenXRI server.
Deploying a .WAR file on Tomcat is usually done by placing the file into the webapps/ directory of Tomcat. In a typical configuration, the name of the .WAR file directly maps to the name of the context, which becomes part of the URL under which your server can be accessed. For example, if you are running Tomcat at your website yourserver.com, and you place the file openxri-server.war into the webapps/ directory, it becomes available at the URL http://yourserver.com/openxri-server/. Note that the path to the authority resolution servlet (by default /resolve) is added at the end, i.e. the full URL of your authority resolution server will be http://www.myserver.com/openxri-server/resolve. Please refer to the documentation of Tomcat or your other servlet container for more information on how to deploy web applications.
Configuring the OpenXRI server
The main configuration file of the OpenXRI server is WEB-INF/server.xml. The settings you should first check and adjust for your environment are:
<properties> <property key="hostname" value="yourserver.com" /> <property key="hostport" value="80" /> <property key="servletpath" value="/openxri-server/resolve/" /> </properties>
The servletpath setting should contain the full path to the web application and to the authority resolution servlet.
Another section of the configuration file you need to pay attention to is the configuration of the Store component. By default it looks like this:
<component interface="org.openxri.store.Store"> <class>org.openxri.store.impl.db.DatabaseStore</class> <properties> <property key="hibernate.connection.url" value="jdbc:derby:openxri;create=true" /> <property key="hibernate.connection.driver_class" value="org.apache.derby.jdbc.EmbeddedDriver" /> <property key="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect" /> <property key="hibernate.show_sql" value="false" /> <property key="hibernate.connection.autoReconnect" value="true" /> <property key="hibernate.connection.autoReconnectForPools" value="true" /> <property key="hibernate.connection.is-connection-validation-required" value="true" /> <property key="hibernate.transaction.factory_class" value="org.hibernate.transaction.JDBCTransactionFactory" /> <property key="hibernate.current_session_context_class" value="thread" /> <property key="hibernate.hbm2ddl.auto" value="update" /> </properties> </component>
These settings determine where the OpenXRI server stores its subsegments, authorities, XRD descriptor documents etc. For this purpose you can use MySQL, PostgreSQL or any other database supported by the Hibernate object/relational persistence service. The default configuration uses Apache Derby, which is a standalone database that does not require external server software.
Deploying the OpenXRI web admin interface
The web admin interface for the OpenXRI server has to be deployed separately. Download it by following the links at
... and deploy it in your servlet container in the same way as the OpenXRI server, e.g. at path /openxri-admin/.
Configuring the OpenXRI web admin interface
The web admin interface also uses the file WEB-INF/server.xml. Both the server and the web admin interface need access to the same information, i.e. you should copy your adjusted server.xml file from one WEB-INF/ directory to the other.
You are now ready to start your Tomcat or other servlet container. You should be able to access the web admin interface at http://yourserver.com/openxri-admin/.
There is one initial step you need to perform in the web admin interface, which is to tell OpenXRI about the root namespace(s) under which you are planning to manage XRI subsegments. To do so, click on the "Store" tab and then on "Create root namespace", which takes you to a page where you can register the root namespace (e.g. =yourname) in the OpenXRI server's store.
That's it! You can view details about the authority of your new root namespace by looking up =yourname in the right-hand "Quick Authority Lookup" box. This should take you to a page with a diagram like the following:
You are now ready to register new XRI subsegments under your own root namespace.
Registering XRI subsegments
The quickest way to register new XRI subsegments is to perform the following steps:
- Enter the parent XRI (e.g. your root namespace =yourname) under which you want to register a new XRI subsegment in the right-hand "Quick Authority Lookup" box.
- Click on the "Create a new XRI subsegment under this XRI authority" button.
- Enter a name for the new XRI subsegment (e.g. *test).
- You are now at a page with details about the new XRI's authority. It should have a diagram like the following:
-
- Scroll down a bit to edit the authority's XRD descriptor document, which controls what endpoint(s) an XRI can resolve to.
- Add the following piece of XML code to the XRD and then click "Update":
<Service> <URI>http://www.google.com</URI> </Service>
Done. If you followed all of the above steps correctly and without problems, your new XRI should be fully resolvable. You can try this via the xri.net proxy resolver by typing this into your browser:
http://xri.net/=yourname*test
You may also want to check the diagram for =yourname again. It should now look like this:
Notes
- The OpenXRI server and web admin interface are two different web applications that access the same underlying store. Apache Derby and other databases do not support this kind of concurrent access very well. If you make changes via the web admin interface and the server does not appear to "see" your changes, you may have to restart your Tomcat or other servlet container.
