NAME

wikiup - upload content to a topic on a Foswiki or TWiki site.

SYNOPSIS

wikiup [options] destination files...

DESCRIPTION

wikiup attaches one or more files to a topic on a site running Foswiki or TWiki. The user must specify the destination topic, the files to upload, and, if required, credentials to access the site. It automatically recognizes the following authentication mechanisms:

• HTTP browser based Basic authentication (e.g. Foswiki::LoginManager::ApacheLogin )

• Foswiki::LoginManager::TemplateLogin

Customized values for parameters may be specified in a configuration file, which contain multiple profiles (either for different wiki sites, or for different ways of uploading to the same site).

Options And Arguments

Arguments

The required arguments (which typically follow any options on the command line) are:

destination

Either the topic view URL or the topic path (see Specifying the destination topic).

files

One or more files to upload.

Options

Options may be abbreviated. Options which take values may be separated from the values by whitespace or the "=" character.

-w integer | --segment=integer

The number of components preceding the web name in a "shortened" URL.

-c comment | --comment=comment

The comment to be associated with the uploaded files.

-f filename | --config=filename

Use an alternative configuration file.

--no-config

Don't read any configuration files.

--insecure

Do not verify host certificates when connecting to hosts using SSL. This should only be necessary when connecting to hosts with self-signed certificates.

-k

Ignore upload errors and plow on ahead.

-p profile | --profile=profile

Use the specified profile.

-u username | --user=username

The wiki username. If not specified the user will be prompted.

--bin_path upload path

The upload path relative to the Wiki's base url. wikiup usually figures this out on its own, but may get it wrong if the wiki is using "shortened" URLs. It falls back to /bin/upload.

-a attrs | --attr=attrs

Specify a comma separated list of attributes. For example,

  --attr=show,link

See Upload Attributes for more information.

-r | --rename

Treat the list of files to be uploaded as a list of pairs of files. The first element in the pair is the filename as it exists on disk, the second is the filename as it should be reported to the wiki. See Renaming uploaded files for more information.

-t perlexpr | --transform perlexpr

The filenames reported to the wiki will be transformed using the supplied Perl expression, which should modify the $_ Perl variable. See Renaming uploaded files for more information.

-i | --interactive

Prompt before uploading each file.

-s seconds | --sleep seconds

Sleep the specified number of seconds between uploads to reduce load and avoid blacklisting. Defaults to 5 seconds.

-n | --dryrun

List which files will be uploaded, but don't actually upload anything.

-v | --verbose

Be verbose about what's happening. Repeating the option increases the verbosity.

--usage

Output very short usage information and exit.

-h | --help

Output short usage information and exit.

--man

Output full usage information and exit.

Specifying the destination topic

How you specify the destination topic path (e.g. Web/Topic) depends in part on how your wiki server is configured. The URL used to view a topic will typically have one of the following forms:

• a "standard" URL

    http://server.name/wiki/<bin>/<view>/<topic path>

  Note that <bin >> may be bin or cgi-bin, and <view >> may be view or view.cgi.

• a "shortened" URL

    http://server.name/wiki/<topic path>

You can specify the destination in one of the following ways:

1. Specify the URL in a profile in the configuration file:

   Create a profile in your $HOME/.wikiuprc configuration file with the base url:

     [ mywiki ]
     url = http://server.name/wiki

   When you use the -p option and the profile has a URL, wikiup will treat the destination provided on the command line as a topic path.

     wikiup -p mywiki Web/Topic ...

   If you forget to put the URL in the configuration file, wikiup will treat the command line destination as a full URL, which won't work.

2. Use a "standard" view URL:

   If the wiki site uses the "standard" form of the view URL, you can cut and paste the view URL from your browser:

     wikiup http://server.name/wiki/bin/view/Web/Topic ...

   wikiup can usually figure out the topic path. If it can't it'll stop and output an error. Please report this as a bug. You can work around this bug using approach 1 above.

3. Use a "shortened" view URL:

   If the wiki site uses the "standard" form of the view URL, you can cut and paste the view URL from your browser.

   Unfortunately in this case wikiup can't reliably figure out where the topic path begins. There are two ways to tell it:

   1. You can use the -w option to tell it the number of segments (after the server name) which precede the topic path in the URL. For example,

        wikiup -w 1 http://server.name/wiki/Web/Topic ...

   2. Create a profile in the configuration file with the base URL:

        [ mywiki ]
        url = http://server.name/wiki

      and specify the shortened URL

        wikiup http://server.name/wiki/Web/Topic ...

      This works because wikiup will try to match against the URL's in profiles if it can't figure out the topic path from the view URL.

Authentication

If the Wiki requires authentication, the user must specify a username and password. If they are not provided via the command line or the configuration file, the user will be prompted. For security reasons, it is not possible to specify the password on the command line.

Profile Matching

If a profile is not specified via the -p option, wikiup will try to select one in the user's configuration file by matching on the base wiki URL.

Upload Attributes

Upload attributes indicate additional actions that can be performed during the upload. They may be specified via the --attrs option or in the configuration file.

show | hide

These attributes indicate whether the uploaded files should be shown in the attachment table.

link | no-link

These attributes indicates whether a link to the attachment should be added in the topic text.

CONFIGURATION FILE

wikup's behavior can be customized using a configuration file. The configuration file must be readable only by the user (because it may contain passwords); if not, wikiup will exit with an error message.

A configuration file may contain multiple profiles (either for different wiki sites, or for different ways of uploading to the same site).

Configuration file format

Lines which begin with # are ignored. Lines which have the form

  variable = value

define configuration variables, and lines which have the form

  [ profile_name ]

define a new profile. Variable definitions which follow a profile definition are part of that profile until a new profile is defined.

Variable definitions which precede profile definitions are used as defaults.

To unset a variable in a profile (e.g. to discard the default value), set it to an empty value.

Variables

The following variables are recognized:

url

The base URL for the wiki site.

user

The wiki user name used to authenticate with the wiki server

password

The password used to authenticate with the wiki server

profile

Specify the default profile. Only useful in the default section of the configuration file.

read_root_config

If present in the default section of a configuration file, it causes the root configuration file ($HOME/.wikiuprc) to be read. (This has no effect if it's in the root configuration file.)

web

The web to which to upload the files. This has meaning only if the url variable is also specified. If this is specified, the command line destination should be the topic name, without a web.

sleep

The number of seconds to sleep between uploads.

insecure

See the --insecure option.

transform

See the --transform option.

segment

See the --segment option.

bin_path

The path (relative to the base URL) of the upload command. By default it is /bin/upload.

Specifying Upload Attributes

Upload attributes are specified in the same manner as variables. Set them to 1 to enable them, 0 to disable them.

Configuration file location

By default wikiup will first look in the current directory for .wikiuprc. If that is not present, or if the read_root_config variable is set it will look for $HOME/.wikiuprc. wikiup can be persuaded to look elsewhere with the -f option.

Configuration File Examples

  # Mickey Mouse has the same username and password on most sites
  user = MickeyMouse
  password = SqueakSqueak

  # Hide attachments and don't create links to them
  hide = 1
  link = 0

  # these are "shortened" URL sites; specify the URL so automatic
  # profile recognition works

  [ site1 ]
  url = http://site1/wiki

  [ site2 ]
  url = http://site2/wiki

  # reset the password so as to force password prompting for this site
  [ site3 ]
  url = http://site3/wiki
  password =

EXAMPLES

Renaming uploaded files

Foswiki and TWiki currently only allow a topic to include an attached file (via %INCLUDE{ "%ATTACHURL%/filename" }%) if it ends in .txt or .html. wikiup supports two means of changing the name that is reported to the wiki server, so that the user doesn't have to rename the file prior to uploading it.

• Use the --rename option:

  --rename instructs wikiup to treat the list of files to be uploaded as a list of pairs of files. The first element in the pair is the filename as it exists on disk, the second is the filename as it should be reported to wiki. For example,

    wikiup -p mysite -r Web/Topic file1.fit file1.fit.txt file2.x file2.txt

  will upload file1.fit as file1.fit.txt and file2.x as file2.txt.

• Use the --transform option:

  This is a more advanced technique which uses a Perl expression to transform the file name. It is most useful when uploading a number of files using a shell glob pattern, as in

    wikiup -p mysite Web/Topic foo.*

  The Perl expression should modify the $_ Perl variable. Here are a couple of examples:

  Rename all files ending in .fit, changing it to .txt, using Perl regular expressions:

    -t 's/.fit$/.txt/'

  Append .txt to all files ending in .fit.

    -t '/.fit$/ and $_ .= ".txt"'
    -t 's/(.*.fit)$/$1.txt'

ERRORS

The following error messages may be output:

Command line errors

no files were specified

No files were specified on the command line.

destination isn't a recognizeable URL: $destination

The URL specified on the command line isn't recognizable as a valid URL.

unable to determine base url from $uri

wikiup was unable to determine which parts of the URL were the path to the wiki web and topic

odd number of filenames: --rename requires an even number

If the --rename option is specified wikiup expects that the filenames on the command line come in pairs. This message indicates that an unpaired filename was specified.

Upload errors

non-existent or unreadable files: %s

The listed files were either not found or were not readable.

error transforming $file: %s

An error ocurred when performing a filename transformation. Check the Perl expression that was specified with the --transform option for syntax.

error accessing Topic: $topic via $url

The wiki server indicated that the requested topic was not valid.

Found Foswiki cookie ($cookie), but host ($host) doesn't match domain ($domain)

There is something wrong on the wiki server. the Foswiki generated cookie is not valid on the wiki server.

Found Foswiki cookie ($key), but path ($path) doesn't match URL $uri

There is something wrong on the wiki server. the Foswiki generated cookie is not valid for the URL of the topic.

unable to find validation key in attach form

There is something wrong on the wiki server. Foswiki generated a STRIKEONE cookie, but the STRIKEONE validation key was not in the attachment form on the wiki attach page for the requested topic.

Configuration file errors

$file: configuration file does not exist

unknown profile: $profile

The profile specified via the --profile option does not exist in the configuration file(s).

illegal attribute: $attr

An attribute was specified which is not valid.

$file: insecure permissions

The configuration flie must be readable only by the owner of the file.

BUGS

None reported.

FILES

$HOME/.wikiuprc

The user's configuration file.

COPYRIGHT AND LICENSE

Copyright 2008-2012 The Smithsonian Astrophysical Observatory. wikiup is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

AUTHOR

Diab Jerius <djerius@cfa.harvard.edu>