1INSTALL.zxid 2============ 3$Id: INSTALL.zxid,v 1.42 2016-02-27 13:36:33 sampo Exp $ 4 5Quick 6----- 7 8 make # beware of need to specify TARGET if not linux; or edit localconf.mk 9 make all # all bindings beyond C (perl, php, Java, mod_auth_saml for Apache httpd) 10 make install 11 12These instructions are for the impatient. See 13<<link:html/zxid-install.html: ZXID Compilation and Installation>> 14aka zxid-install.pd for the complete story. 15 16If you want to try ZXID out immediately, we recommend compiling the 17library and examples and installing one of the examples as a CGI 18script in an existing web server. 19 20Install Packages for Your Distribution 21-------------------------------------- 22 23TBD (*** WIP) 24 25 # Redhat derived systems 26 yum install zxid 27 28 or 29 30 # Debian derived systems 31 apt-get install zxid 32 33Move to section "Configuration and Canned Demo", below. 34 35Compilation from Source 36----------------------- 37 38Download and extract the source 39 40 wget http:/zxid.org/zxid-1.42.tgz # Check for newer version, please 41 tar xvzf zxid-1.42.tgz 42 cd zxid-1.42 43 44Compile all packages (C, perl, php, Java, and apache httpd interfaces) 45 46 # N.B. There is no configure script. The Makefile works for all 47 # supported platforms by provision of correct TARGET option. 48 49 make all # Compile for ix86 Linux (default), all bindings 50 make all TARGET=sol8 # Compile for Solaris 51 make all TARGET=macosx # Compile for MacOS X (ix86 tested) 52 make all TARGET=xmingw # Cross compile Windows binaries using Linux 53 54 # If errors, see section "Compilation Problems", below, and zxid-faq.pd 55 56 make install 57 ln -s /var/zxid/1.42 /var/zxid/std # Change to match actual release 58 export PATH=/var/zxid/std/bin:$PATH 59 60Move to section "Configuration and Canned Demo", below. 61 62Configuration and Canned Demo 63----------------------------- 64 65For detailed configuration reference, please see 66<<link:html/zxid-conf.html: ZXID Configuration Reference>> aka 67zxid-conf.pd 68 69For canned demo you need an IdP and a SP. Here's how: 70 71 export PATH=/var/zxid/std/bin:$PATH # if not already done 72 73 zxcot -dirs # For the SP 74 echo NICE_NAME=Your SP Branding >/var/zxid/zxid.conf 75 echo ORG_NAME=Your Organization >>/var/zxid/zxid.conf 76 echo ORG_URL=http://your.org/ >>/var/zxid/zxid.conf 77 echo URL=http://sp1.zxidsp.org:8443/zxidhlo >>/var/zxid/zxid.conf 78 79 zxcot -dirs /var/zxid/idp/ # For the IdP 80 echo NICE_NAME=Your IdP Branding >/var/zxid/idp/zxid.conf 81 echo ORG_NAME=Your IdP Organization >>/var/zxid/idp/zxid.conf 82 echo ORG_URL=http://youridp.org/ >>/var/zxid/idp/zxid.conf 83 echo URL=http://idp1.zxid.org:8443/zxididp >>/var/zxid/idp/zxid.conf 84 85In the above, the configuration files for SP and IdP were created. Some 86configuration options are actually set in the source code of the respective 87applications. In the config files you MUST set 88 89NICE_NAME:: Used for user interface purposes (displayed to user) to identify the site. 90ORG_NAME:: The name of the legal entity responsible for the site, shown to user. 91ORG_URL:: Institutional web site of the legal entity, shown to user. 92URL:: Entity Id of the web site. For demo, set them as shown (often set in source). 93 94Running 95------- 96 97 cp zxidhlo* <webroot>/ 98 # configure and start your web server to recognize zxidhlo a CGI, e.g. 99 mini_httpd -p 8443 -c 'zxid*' -S -E zxid.pem 100 101 # Edit your /etc/hosts to contain (on Windows C:\Windows\System32\etc\hosts) 102 127.0.0.1 localhost sp1.zxidcommon.org sp1.zxidsp.org 103 104 # Point your browser to (zxid_simple() API version) 105 https://sp1.zxidsp.org:8443/zxidhlo?o=E 106 https://sp1.zxidsp.org:8443/zxidhlo.pl?o=E # Perl version 107 https://sp1.zxidsp.org:8443/zxidhlo.php?o=E # PHP version 108 https://sp1.zxidsp.org:8443/zxidhlo-java.sh?o=E # Java version 109 110 # Find an IdP to test with and configure it... 111 # ... e.g. download from http://symlabs.com/Products/SFIAM.html 112 113See zxid-install.pd for actual tutorial out-of-box experience. 114 115Compilation Problems 116-------------------- 117 118See also: zxid-faq.pd (*** also in zxid-faq.pd) 119 120* Makefile tries to compile a bunch of check programs early in the 121 compilation to detect common problems with missing headers (include 122 files) and missing libraries. 123 124* If the checks fail, you need to adjust the -I and -L flags in Makefile 125 variables CINC and LIBS (around lines 136 and 149). 126 127* Else you can create localconf.mk file (recommended), that will be 128 included by the main Makefile, and put your modifications there. 129 130* If you have difficulty in finding the headers and libraries (or whether 131 a package is installed at all), try the following commands 132 133 find / -name 'stdio.h' 134 find / -name 'libc.*' 135 find / -name 'zlib.h' 136 find / -name 'libz.*' 137 find / -name 'opensslv.h' 138 find / -name 'libssl.*' 139 find / -name 'libcrypto.*' 140 find / -name 'curlver.h' 141 find / -name 'libcurl.*' 142 find / -name 'ap_release.h' 143 find / -name 'apr_version.h' 144 find / -name 'libapr-1.*' 145 find / -name 'servlet-api.jar' 146 147 If you find more than one of any of the above, you need to be extra 148 careful about which one you use. 149 150* ZXID dependency libraries are libcurl, openssl (libssl, libcrypto), and zlib 151 152 If the prerequisite libaries - libz, libssl, libcrypto, and libcurl 153 - are genuinely missing, you should either compile them yourself, or 154 install dev packages of those libraries from your distribution. 155 156* Usually you can use the versions that are supplied with your distribution. 157 However in this case you MUST install also the headers. Usually these 158 are called "development" packages. For example 159 160 # Redhat derived systems 161 yum install gcc # Usually installs libc and libz headers 162 yum install openssl-devel 163 yum install curl-devel 164 165 or 166 167 # Debian derived systems 168 apt-get install gcc # Usually installs libc and libz headers 169 apt-get install openssl-devel 170 apt-get install curl-devel 171 172 If all else fails, compile the dependencies 173 from source. 174 175* zxid assumes openssl, libcurl, Java, and Apache to be installed 176 in the locations where source distributions of those packages 177 install them in their default configuration (e.g. /usr/local/ssl, 178 /usr/local/httpd, etc.) 179 180* Many distributions (e.g. Ubuntu, Redhat, SUSE, ...) choose to install 181 those libraries in different places, thus requiring distribution 182 specific edits to localconf.mk, see the find(1) commands above. 183 184 echo 'CURL_ROOT=/usr' >>localconf.mk 185 echo 'OPENSSL_ROOT=/usr' >>localconf.mk 186 187* The make all command attempts to build all language bindings and 188 Apache module. If you do not need all bindings, you can build 189 only the part relevant to you (and avoid errors irrelevant to you): 190 191 make # Compile C library for ix86 Linux (default) 192 193 make apachezxid # optional: compile mod_auth_saml Apache module 194 make apachezxid_install # optional: install mod_auth_saml.so 195 196 make samlmod # optional: compile Net::SAML perl module 197 make samlmod_install # optional: install Net::SAML 198 199 make phpzxid # optional: compile php_zxid PHP extension 200 make phpzxid_install # optional: install php_zxid.so 201 202 make javazxid # optional: compile libzxidjni 203 make javazxid_install # optional: install libzxidjni.so and zxidjni.class 204 205 206Trouble Shooting 207---------------- 208 209 # N.B2: We distribute some generated files. If they are missing, you need 210 # to regenerate them: make cleaner; make dep ENA_GEN=1 211 212 make dir # Creates /var/zxid hierarchy 213 214 215--Sampo 216