diff --git a/docs/.gitignore b/docs/.gitignore index e5b3c00fa..fb2e3bf6e 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ -auth.md \ No newline at end of file +auth.md +auth.html diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index a3cd2f628..4562745ea 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -4,7 +4,7 @@ IF(ENABLE_DOXYGEN) # The following is redundant but does not hurt anything. - FILE(GLOB COPY_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.html ${CMAKE_CURRENT_SOURCE_DIR}/images ${CMAKE_CURRENT_SOURCE_DIR}/*.doc ${CMAKE_CURRENT_SOURCE_DIR}/*.xml ${CMAKE_CURRENT_SOURCE_DIR}/*.m4 ${CMAKE_CURRENT_SOURCE_DIR}/*.texi) + FILE(GLOB COPY_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.html ${CMAKE_CURRENT_SOURCE_DIR}/images ${CMAKE_CURRENT_SOURCE_DIR}/*.doc ${CMAKE_CURRENT_SOURCE_DIR}/*.xml ${CMAKE_CURRENT_SOURCE_DIR}/*.m4 ${CMAKE_CURRENT_SOURCE_DIR}/*.texi ${CMAKE_SOURCE_DIR}/oc2/auth.html.in) FILE(COPY ${COPY_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/) @@ -18,11 +18,16 @@ IF(ENABLE_DOXYGEN) CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY) - # Create auth.md by combining auth.md.in and oc2/ocauth.md + # Create auth.html with some sed commands. + ADD_CUSTOM_TARGET(auth_doc_html ALL + cat ${CMAKE_CURRENT_BINARY_DIR}/auth.html.in | sed -e "//d" | sed -e "s|^||" | sed -e "s|zz|netcdf|g" -e "s|ZZ|netCDF|g" | sed -e "/stylesheet/r${CMAKE_SOURCE_DIR}/oc2/oc.css" -e "/stylesheet/d" > ${CMAKE_CURRENT_BINARY_DIR}/auth.html + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + VERBATIM + ) - ADD_CUSTOM_TARGET(auth_doc ALL - cat ${CMAKE_SOURCE_DIR}/docs/auth.md.in ${CMAKE_SOURCE_DIR}/docs/ocauth.md > ${CMAKE_CURRENT_SOURCE_DIR}/auth.md - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + ADD_CUSTOM_TARGET(auth_doc_md ALL + cat ${CMAKE_CURRENT_BINARY_DIR}/auth.html | sed "1,46d" > ${CMAKE_CURRENT_BINARY_DIR}/auth.md + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} VERBATIM ) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 2122296de..7310bb627 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -754,7 +754,7 @@ INPUT = \ @abs_top_srcdir@/docs/windows-binaries.md \ @abs_top_srcdir@/docs/guide.dox \ @abs_top_srcdir@/docs/OPeNDAP.dox \ - @abs_top_srcdir@/docs/auth.md \ + @abs_builddir@/auth.md \ @abs_top_srcdir@/docs/attribute_conventions.md \ @abs_top_srcdir@/docs/file_format_specifications.md \ @abs_top_srcdir@/docs/tutorial.dox \ diff --git a/docs/auth.html b/docs/auth.html index c617e86c2..72a7aa70e 100644 --- a/docs/auth.html +++ b/docs/auth.html @@ -2,54 +2,17 @@ - + -

netCDF Authorization Support

+

ZZ Authorization Support

Author: Dennis Heimbigner

Address: http://www.unidata.ucar.edu/staff/dmh/

Draft: 11/21/2014

Last Revised: 10/24/2015

+

ZZ Version 4.0

Table of Contents

@@ -65,7 +28,7 @@ h4:before {

Introduction

-netCDF can support user authorization using the facilities provided by the curl +ZZ can support user authorization using the facilities provided by the curl library. This includes basic password authentication as well as certificate-based authorization.

@@ -91,8 +54,8 @@ authorization will not work with this because the username and password will only be used on the initial request, not the redirection

RC File Authentication

-The netcdf library supports an rc file mechanism to allow the passing -of a number of parameters to libnetcdf and libcurl. +The zz library supports an rc file mechanism to allow the passing +of a number of parameters to libzz and libcurl.

The file must be called one of the following names: ".daprc" or ".dodsrc" @@ -102,6 +65,10 @@ the .daprc file will take precedence. The rc file is searched for first in the current directory and then in the home directory (as defined by the HOME environment variable). +It is also possible to specify a direct path using +the -R option to ocprint or using the oc_set_rcfile +procedure (see oc.h). Note that for these latter cases, the path +must be to the file itself, not to the containing directory.

The rc file format is a series of lines of the general form: 

@@ -210,11 +177,24 @@ where the machine, mmmmmm, is the hostname of the machine to
 which the client is redirected for authorization, and the
 login and password are those needed to authenticate on that machine.
 

-The .netrc file can be specified by
-putting the following line in your .daprc/.dodsrc file.
-
-HTTP.NETRC=<path to netrc file>
-

+The .netrc file can be specified by
+putting the following line in your .daprc/.dodsrc file.
+
+HTTP.NETRC=<path to netrc file>
+

+The .netrc file can be specified in two ways.
+
    
+
  1.  Specify the netrc file to libzz using the procedure in oc.h:
+
    +oc_set_netrc(OClink* link, const char* file)
+
    
+(This is equivalent to the -N flag to ocprint). 
+
    
+
  2.  Put the following line in your .daprc/.dodsrc file.
+
    +HTTP.NETRC=<path to netrc file>
+
    
+

 
 

 One final note. In using this, it is almost certain that you will
@@ -236,7 +216,7 @@ Examples.
 or
 [fake.ucar.edu:9090]HTTP.VERBOSE=0
-If the url request from, say, the netcdf_open method +If the url request from, say, the zz_open method has a host+port matching one of the prefixes in the rc file, then the corresponding entry will be used, otherwise ignored.

@@ -293,7 +273,7 @@ the code is definitive.

Appendix B. URS Access in Detail

It is possible to use the NASA Earthdata Login System (URS) -with netcdf by using using the process specified in the +with zz by using using the process specified in the redirection based authorization section. In order to access URS controlled datasets, however, it is necessary to register as a user with NASA at the @@ -302,12 +282,12 @@ website.

Appendix C. ESG Access in Detail

It is possible to access Earth Systems Grid (ESG) datasets -from ESG servers through the netCDF API using the techniques +from ESG servers through the ZZ API using the techniques described in the section on Client-Side Certificates.

In order to access ESG datasets, however, it is necessary to register as a user with ESG and to setup your environment -so that proper authentication is established between an netcdf +so that proper authentication is established between an zz client program and the ESG data server. Specifically, it is necessary to use what is called "client-side keys" to enable this authentication. Normally, when a client accesses @@ -317,7 +297,7 @@ With client-side keys, the client must also provide a certificate to the server so that the server can know with whom it is communicating.

-The netcdf library uses the curl library and it is that +The zz library uses the curl library and it is that underlying library that must be properly configured.

Terminology