Man Linux: Main Page and Category List

NAME

       gnunet-insert - a command line interface for inserting new content into
       GNUnet

SYNOPSIS

       gnunet-insert [OPTIONS] FILENAME

DESCRIPTION

       In order to share files with other GNUnet users, the files  must  first
       be  made  available to GNUnet.  GNUnet does not automatically share all
       files  from  a  certain  directory.   In  fact,  even  files  that  are
       downloaded are not automatically shared.

       In  order  to start sharing files, the files must be added either using
       gnunet-insert or gnunet-gtk.  The command line  tool  gnunet-insert  is
       more  useful if many files are supposed to be added.  gnunet-insert can
       automatically insert batches of files, recursively insert  directories,
       create  directories  that can be browsed within GNUnet and publish file
       lists in a namespace.  When run  on  a  directory,  gnunet-insert  will
       always recursively publish all of the files in the directory.

       gnunet-insert  can  automatically  extract keywords from the files that
       are shared.  Users that want to download files from GNUnet use keywords
       to  search  for  the  appropriate  content.   You  can  disable keyword
       extraction with the -D option.  You can manually add keywords using the
       -k and -K options.

       In addition to searching for files by keyword, GNUnet allows organizing
       files into directories.  With directories, the user only needs to  find
       the  directory  in order to be able to download any of the files listed
       in  the  directory.   Directories  can  contain   pointers   to   other
       directories.

       With gnunet-insert, it is easy to create new directories simultaneously
       when adding the files.  Simply pass the name of a directory instead  of
       a file.

       Since  keywords  can be spammed (any user can add any content under any
       keyword), GNUnet supports namespaces.  A namespace is a subset  of  the
       searchspace  into  which only the holder of a certain pseudonym can add
       content.  Any GNUnet user can create any  number  of  pseudonyms  using
       gnunet-pseudonym-create.  Pseudonyms  are  stored  in  the users GNUnet
       directory and can be additionally protected  with  a  password.   While
       pseudonyms  are  locally  uniquely  identified with an arbitrary string
       that the user selects when the pseudonym is created, the globally  only
       the  hash  of  the public key is guaranteed to be unique.  However, the
       locally chosen name is added to the  meta-data  as  the  title  of  the
       namespace.   Since  only  the owner of the pseudonym can add content to
       the namespace,  it  is  impossible  for  other  users  to  pollute  the
       namespace.   gnunet-insert  automatically inserts the top-directory (or
       the only file if only one file is specified) into the  namespace  if  a
       pseudonym   is  specified.   If  no  specific  namespace-identifier  is
       specified (option -t), gnunet-insert selects a random identifier.

       It is possible to update content in GNUnet if that content  was  placed
       and  obtained  from  a particular namespace.  Updates are only possible
       for content in namespaces since this is the only way to assure  that  a
       malicious  party can not supply counterfeited updates.  GNUnet supports
       two types of  updateable  content,  sporadically  updated  content  and
       periodically updated content. If content is periodically updated (every
       day, every week, etc.), the period must be passed to gnunet-insert with
       the  -i  option. The -S option is used to indicate sporadically updated
       content. You can use the -N option to specify the future identifier  of
       the update (only for the first update of periodically updated content).
       Without -N, gnunet-insert will select (and output) a random  identifier
       that  must  be  used for the next update.  You can use the option -u to
       specify the identifier of the previous version of the content that  you
       want to update.

       You  can  use automatic meta-data extraction (based on libextractor) or
       the command-line option -m to specify meta-data.  For the -m option you
       need  to  use  the  form  keyword-type:value.   For  example,  use  "-m
       os:Linux" to specify  that  the  operating  system  is  Linux.   Common
       meta-data   types  are  "author",  "title"  ,  "mimetype",  "filename",
       "language", "subject" and "keywords".  A full list can be obtained from
       the  extract  tool  using  the option --list.  The meta-data is used to
       help users in searching for files on the  network.   The  keywords  are
       case-sensitive.

       GNUnet  supports  two  styles  of  publishing  files  on  the  network.
       Inserting a file means that a copy of the file is made in the local (!)
       database  of the node.  Indexing a file means that an index is added to
       the local (!)  database with symbolic links to the  file  itself.   The
       links  will  use  the  SHA-512 hash of the entire file as the filename.
       Indexing is generally significantly  more  efficient  and  the  default
       choice.   However,  indexing only works if the indexed file can be read
       (using the same absolute path) by gnunetd.  If this is  not  the  case,
       indexing  will  fail  (and  gnunet-insert  will automatically revert to
       inserting instead).  Regardless of which method is used to publish  the
       file,  the  file will be slowly (depending on how often it is requested
       and on how much bandwidth is available) dispersed into the network.  If
       you  insert  or index a file and then leave the network, it will almost
       always NOT be available anymore.

       -c FILENAME, --config=FILENAME  Use  alternate  config  file  (if  this
       option is not specified, the default is ~/.gnunet/gnunet.conf).

       -C,  --copy  Even  if using links to the .gnunet directory is generally
       permitted, make a copy of the file (disables symlinking even if  it  is
       possible).   When  indexing a file, gnunet-insert will create a copy of
       the file in the  "share"  directory  of  gnunetd.   If  that  directory
       happens  to  be  on  the local machine (i.e. gnunetd runs on localhost)
       then gnunet-insert can instead just use a link.   This  will  not  work
       over  the network, if the file-permissions do not allow gnunetd to read
       the file or if the file maybe changed afterwards.  Hence the default is
       to  be  inefficient and to make a copy.  With this option you can force
       gnunet-insert to not make a link.   gnunet-insert  will  fall  back  to
       creating a copy.

       -D, --disable-direct
              Disable  direct  indexing information that would otherwise refer
              to files inside of directories directly.  Without  -D,  contents
              can   be   found   directly   using   keywords   extracted  with
              libextractor.  Use -D if you index directories with many similar
              files  that  are  adequately  described  using  keywords for the
              directory and for  which  individual  references  would  unduely
              pollute the global keyword search space.  Also use -D to disable
              libextractor for individual file publications.  This way you can
              ensure  that  a  file will only be referenced using the keywords
              that you are specifying explicitly.

       -e, --extract
              Print the list of keywords  that  will  be  extracted.   Do  not
              perform any indexing or insertion.

       -h, --help
              Print a brief help page with all the options.

       -H HOSTNAME, --host=HOSTNAME
              on  which host is gnunetd running (default: localhost).  You can
              also specify a port using the syntax HOSTNAME:PORT.  The default
              port is 2087.

       -k KEYWORD, --key=KEYWORD
              additional  key to index the content with (to add multiple keys,
              specify multiple times). Each additional key is  case-sensitive.
              Can be specified multiple times.  The keyword is only applied to
              the top-level files or directories.

       -K KEYWORD, --global-key=KEYWORD
              additional key to index the content  with.   Keywords  specified
              with  -K are applied to files and directories encountered on the
              command-line or  in  the  recursive  scan.   This  is  the  only
              difference  to  the  -k  option.   This  option can be specified
              multiple times.

       -L LOGLEVEL, --loglevel=LOGLEVEL
              Change the loglevel.  Possible values for LOGLEVEL are  NOTHING,
              FATAL,  ERROR,  WARNING,  INFO,  STATUS  and  DEBUG.   Note that
              options in the configuration  file  take  precedence  over  this
              option (the argument will be ignored in that case).

       -m TYPE:VALUE, --meta=TYPE:VALUE
              For  the main file (or directory), set the metadata of the given
              TYPE to the given VALUE.   Note  that  this  will  not  add  the
              respective VALUE to the set of keywords under which the file can
              be found.

       -n, --noindex
              Executive summary: You probably don’t need it.

              Do not index, full insertion.  Note that  directories,  RBlocks,
              SBlocks  and  IBlocks  are  always  inserted  (even without this
              option).  With this option, every block of the actual  files  is
              stored  in  encrypted  form  in  the block database of the local
              peer.  While this adds security if the local node is compromised
              (the  adversary  snags  your  machine), it is significantly less
              efficient compared to on-demand encryption and is definitely not
              recommended for large files.

       -N ID, --next=ID
              Specifies  the  next ID of a future version of the SBlock.  This
              option is only valid together with the -P option.   This  option
              can be used to specify what the identifier of an updated version
              will look like.  Without the -i option, a one-shot update SBlock
              is  used  (a-periodic).   With  the  -i  option,  the difference
              between the current ID (this) and the next ID is used to compute
              all  future  IDs.   Note  that  specifying  -i and -N without -t
              hardly ever makes sense.

       -p PRIORITY, --prio=PRIORITY
              Executive summary: You probably don’t need it.

              Set the priority of the inserted content (default: 365).  If the
              local database is full, GNUnet will discard the content with the
              lowest ranking.  Note that ranks change over time  depending  on
              popularity.   The  default should be high enough to preserve the
              locally inserted content in favor of content that migrates  from
              other peers.

       -P NAME, --pseudonym=NAME
              For  the  top-level  directory  or  file,  create an SBlock that
              places the file into the namespace specified  by  the  pseudonym
              NAME.   When  using  -P,  you  must  also  use  the option -t to
              specifiy which identifier should be used for the  entry  in  the
              namespace.

       -s, --simulate-only
              When  this  option  is  used,  gnunet-insert  will  not actually
              publish the file but just simulate what would be done.  This can
              be  used  to  compute the GNUnet URI for a file without actually
              sharing it.

       -t ID, --this=ID
              Specifies the ID of the  SBlock.   This  option  is  only  valid
              together  with the -P option and together with either the option
              -b or only a single filename on the command-line.

       -u URI, --uri=URI
              This option can be used to specify the URI of a file instead  of
              a  filename (this is the only case where the otherwise mandatory
              filename argument must be omitted).   Instead  of  publishing  a
              file or directory and using the corresponding URI, gnunet-insert
              will use this URI and perform the selected namespace or  keyword
              operations.   This  can  be used to add additional keywords to a
              file that has already been shared or to add files to a namespace
              for  which  the  URI  is  known  but  the content is not locally
              available.

       -v, --version
              Print the version number.

       -V, --verbose
              Be verbose.  Using this option  causes  gnunet-insert  to  print
              progress information and at the end the file identification that
              can be used to download the file from GNUnet.

EXAMPLES

       Basic examples

       Index a file COPYING:

        # gnunet-insert COPYING

       Insert a file COPYING:

        # gnunet-insert -n COPYING

       Index a file COPYING with the keywords gpl and test:

        # gnunet-insert -k gpl -k test COPYING

       Index  a  file  COPYING  with  description  "GNU  License",   mime-type
       "text/plain" and keywords gpl and test:

        #  gnunet-insert  -m  "description:GNU  License"  -k  gpl  -k  test -m
       "mimetype:text/plain" COPYING

       Using directories

       Index the files COPYING and AUTHORS  with  keyword  test  and  build  a
       directory   containing  the  two  files.   Make  the  directory  itself
       available under  keyword  gnu  and  disable  keyword  extraction  using
       libextractor:

        # mkdir gnu
        # mv COPYING AUTHORS gnu/
        # gnunet-insert -K test -k gnu -D gnu/

       Neatly  publish  an  image  gallery  in kittendir/ and its subdirs with
       keyword kittens for the directory but no keywords  for  the  individual
       files or subdirs (-n).  Force description for all files:

        #  gnunet-insert  -n  -m  "description:Kitten  collection"  -k kittens
       kittendir/

       Secure publishing with namespaces

       Insert file COPYING with pseudonym RIAA-2 (-P) and with identifier  gpl
       (-t) and no updates:

        # gnunet-insert -P RIAA-2 -t gpl COPYING

       Recursively  index  /home/ogg and build a matching directory structure.
       Insert the top-level directory into the namespace under  the  pseudonym
       RIAA-2  (-P)  under  identifier  ’MUSIC’ (-t) and promise to provide an
       update with identifier ’VIDEOS’ (-N):

        # gnunet-insert -P RIAA-2 -t MUSIC -N VIDEOS /home/ogg

       Recursively insert (-n) /var/lib/mysql and build a  matching  directory
       structure,  but  disable  the  use  of libextractor to extract keywords
       (-n).  Print the file identifiers (-V) that can be used to retrieve the
       files.   This  will  store  a  copy of the MySQL database in GNUnet but
       without adding any keywords to search for it.  Thus  only  people  that
       have  been  told the secret file identifiers printed with the -V option
       can retrieve the (secret?) files:

        # gnunet-insert -nV /var/lib/mysql

       Create a namespace entry ’root’ in namespace MPAA-1 and  announce  that
       the next update will be called ’next’:

        # gnunet-insert -P MPAA-1 -t root -N next noise.mp3

       Update the previous entry, do not allow any future updates:

        # gnunet-insert -P MPAA-1 -t next noise_updated.mp3

NOTES

       As  most  GNUnet  command-line  tools,  gnunet-insert  supports passing
       arguments using environment variables.  This can improve  your  privacy
       since otherwise the published filenames will likely be visible to other
       local users.  Setting "GNUNET_ARGS" will cause the respective string to
       be appended to the actual command-line and to be processed the same way
       as arguments given directly at the command line.

FILES

       ~/.gnunet/gnunet.conf
              GNUnet configuration file

REPORTING BUGS

       Report bugs by using mantis <https://gnunet.org/bugs/>  or  by  sending
       electronic mail to <gnunet-developers@gnu.org>

SEE ALSO

       gnunet-auto-share(1),        gnunet-gtk(1),        gnunet-pseudonym(1),
       gnunet-search(1),   gnunet-download(1),   gnunet.conf(5),   gnunetd(1),
       extract(1)